maquina 0.5.2 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f39a0b2ab151429d764ab650eeb2000b0d7f273f2d8db62432eb331f46ae5609
-  data.tar.gz: ff0518eb8328e885ef95245e3faad7fecf7f7a69637c00f967a2efb7d0a34d2f
+  metadata.gz: 4b1650769946b608a9ed3993d2aeae3107961d2fdf57400f1db5a6a3b66cd10a
+  data.tar.gz: 8dada0a36f41e6c3d8c23c830c2456ff7eeac792221d8a0a6163bdd645865765
 SHA512:
-  metadata.gz: 27a55a0eefda11374168612994a6fdf4b2f13c9264483aadc894c77b881231a8ac84ff5594698e30fedb5aca57b3a221a0b46c0b2f560463f28538555786ae74
-  data.tar.gz: 591238b607bf082ff2247ff83391cbfac9738827dd3043e1c8958b1812394dff383556569d15cc11b0c381e2f3f862bd642191f57e1e3ffd8cfe605898e81372
+  metadata.gz: b573303faa3ffa46a65ed9ac71c7ec8f80a034e49f50ff2fdb6c234289c705472e33118ee5523889fa8216b76db0a8c5034f1dd0b76719631d3b67d94dd0dc12
+  data.tar.gz: 1748332d65ea73bf86e696b6dd3b52b4534dbf9eb9a05ae12c66bd75d2e64387b73ab9f8347d05309053803740924cace533c4fb49e16bd68d7b78ab201f7b00

data/.ruby-version

@@ -1 +1 @@
-3.3.4
+3.3.5

data/Gemfile

@@ -10,7 +10,9 @@ gem "pg_search"
 gem "puma"
 gem "propshaft"
 gem "tailwindcss-rails"
+gem "importmap-rails"
 gem "turbo-rails"
+gem "stimulus-rails"
 
 # Start debugger with binding.b [https://github.com/ruby/debug]
 #

data/Gemfile.lock

@@ -1,18 +1,15 @@
 PATH
   remote: .
   specs:
-    maquina (0.5.2)
+    maquina (0.7.2)
       action_policy (>= 0.6.0)
       bcrypt (>= 3.1.7)
-      importmap-rails (>= 2.0.0)
       money-rails (>= 1.15.0)
       pagy (>= 6.2)
       phlex-rails (>= 1.1.0)
       rails (>= 7.0.4)
       rotp (>= 6.2.1)
-      stimulus-rails (>= 1.3.0)
       tailwindcss-rails (>= 2.1.0)
-      turbo-rails (>= 2.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -92,10 +89,8 @@ GEM
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.2)
-    backport (1.2.0)
     base64 (0.2.0)
     bcrypt (3.1.20)
-    benchmark (0.3.0)
     bigdecimal (3.1.8)
     brakeman (6.2.1)
       racc
@@ -114,9 +109,7 @@ GEM
     debug (1.9.2)
       irb (~> 1.10)
       reline (>= 0.3.8)
-    diff-lcs (1.5.1)
     drb (2.2.1)
-    e2mmap (0.1.0)
     erubi (1.13.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
@@ -130,12 +123,7 @@ GEM
     irb (1.14.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    jaro_winkler (1.6.0)
     json (2.7.2)
-    kramdown (2.4.0)
-      rexml
-    kramdown-parser-gfm (1.1.0)
-      kramdown (~> 2.0)
     language_server-protocol (3.17.0.3)
     launchy (3.0.1)
       addressable (~> 2.8)
@@ -239,14 +227,11 @@ GEM
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
     rake (13.2.1)
-    rbs (2.8.4)
     rdoc (6.7.0)
       psych (>= 4.0.0)
     regexp_parser (2.9.2)
     reline (0.5.10)
       io-console (~> 0.5)
-    reverse_markdown (2.1.1)
-      nokogiri
     rexml (3.3.7)
     rotp (6.3.0)
     rubocop (1.65.1)
@@ -273,22 +258,6 @@ GEM
     ruby-next-core (1.0.3)
     ruby-progressbar (1.13.0)
     securerandom (0.3.1)
-    solargraph (0.50.0)
-      backport (~> 1.2)
-      benchmark
-      bundler (~> 2.0)
-      diff-lcs (~> 1.4)
-      e2mmap
-      jaro_winkler (~> 1.5)
-      kramdown (~> 2.3)
-      kramdown-parser-gfm (~> 1.1)
-      parser (~> 3.0)
-      rbs (~> 2.0)
-      reverse_markdown (~> 2.0)
-      rubocop (~> 1.38)
-      thor (~> 1.0)
-      tilt (~> 2.0)
-      yard (~> 0.9, >= 0.9.24)
     standard (1.40.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -310,7 +279,6 @@ GEM
     tailwindcss-rails (2.7.3-arm64-darwin)
       railties (>= 7.0.0)
     thor (1.3.2)
-    tilt (2.4.0)
     timeout (0.4.1)
     turbo-rails (2.0.6)
       actionpack (>= 6.0.0)
@@ -324,7 +292,6 @@ GEM
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
-    yard (0.9.37)
     zeitwerk (2.6.18)
 
 PLATFORMS
@@ -335,6 +302,7 @@ DEPENDENCIES
   brakeman
   bundle-audit
   debug (>= 1.0.0)
+  importmap-rails
   irb
   letter_opener
   maquina!
@@ -342,9 +310,9 @@ DEPENDENCIES
   pg_search
   propshaft
   puma
-  solargraph
   standard
   standard-rails
+  stimulus-rails
   tailwindcss-rails
   turbo-rails
 

data/app/assets/javascripts/controllers/alert_controller.js

@@ -0,0 +1,22 @@
+import { Controller } from "@hotwired/stimulus"
+import { enter, leave } from "el-transition"
+
+/**
+ * Alert Controller
+ *
+ * Displays Rails flash messages with animation using el-transition.
+ * Auto-dismisses after 10 seconds or manual close.
+ */
+export default class extends Controller {
+  static targets = ["alert"];
+
+  connect() {
+    enter(this.alertTarget).then(() => {
+      setTimeout(this.close.bind(this), 10000)
+    })
+  }
+
+  close() {
+    leave(this.alertTarget)
+  }
+}

data/app/assets/stylesheets/maquina/application.tailwind.css

@@ -1,101 +1,4 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-/* @layer base { */
-:root {
-  --color-base: 31 27 54;
-  --color-accented:  37 99 235;
-  --color-inverted: 255 255 255;
-  --color-accented-hover: 59 130 246;
-  --color-muted: 55 65 81;
-  --color-dimmed: 75 85 99;
-  --color-error: 220 38 38;
-
-  --color-border-base: 209 213 219;
-  --color-border-accented:  37 99 235;
-}
-
-.label {
-  @apply text-sm font-medium text-skin-muted;
-}
-
-.input {
-  @apply appearance-none rounded-md border border-skin-base px-3 py-2 placeholder-gray-400 shadow-sm focus:border-skin-accented focus:outline-none focus:ring-skin-accented sm:text-sm;
-}
-
-.link {
-  @apply font-medium text-skin-accented hover:text-skin-accented-hover;
-}
-
-.check {
-  @apply border-skin-base h-4 w-4 text-skin-accented focus:ring-skin-accented rounded;
-}
-
-.button {
-  @apply inline-flex justify-center py-2 px-4 border border-skin-base rounded-md shadow-sm text-sm font-medium text-skin-muted bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-skin-accented;
-}
-
-.control-error .label {
-  @apply text-skin-error;
-}
-
-.control-error .input {
-  @apply border-skin-error focus:border-skin-error focus:ring-skin-error;
-}
-
-.help {
-  @apply mt-2 text-sm text-skin-dimmed;
-}
-
-.help-error {
-  @apply text-skin-error;
-}
-
-.button[disabled] {
-  @apply bg-gray-50 text-skin-dimmed cursor-default;
-}
-
-.button-accented {
-  @apply rounded-md border border-transparent bg-skin-accented py-2 px-4 text-sm font-medium text-skin-inverted shadow-sm hover:bg-skin-accented-hover focus:outline-none focus:ring-2 focus:ring-skin-accented focus:ring-offset-2;
-}
-
-input[type="search"] {
-  @apply block w-full rounded-md border border-skin-base pl-10 leading-5 placeholder-gray-400 focus:placeholder-gray-300 focus:outline-none focus:ring-1 focus:ring-skin-accented focus:border-skin-accented sm:text-sm;
-}
-
-.desktop-menu {
-  @apply hidden lg:ml-6 lg:flex lg:space-x-8;
-}
-
-.desktop-menu-item {
-  @apply font-sans uppercase border-transparent text-skin-dimmed underline-offset-4 decoration-2 hover:underline hover:decoration-skin-accented hover:text-skin-muted inline-flex items-center px-1 pt-1 text-sm font-medium;
-}
-
-.desktop-menu-item__active {
-  @apply decoration-skin-accented underline text-skin-base;
-}
-
-.mobile-menu {
-  @apply pt-2 pb-3 space-y-1;
-}
-
-.mobile-menu-item {
-  @apply font-sans border-transparent text-skin-dimmed hover:bg-gray-200 hover:border-gray-300 hover:text-skin-muted block pl-3 pr-4 py-2 border-l-4 text-base font-medium;
-}
-
-.mobile-menu-item__active {
-  @apply bg-skin-accented-hover border-skin-accented text-skin-accented hover:text-skin-accented hover:bg-skin-accented-hover hover:border-skin-accented;
-}
-
-.desktop-profile-menu-item {
-  @apply block w-full text-left font-sans px-4 py-2 text-sm text-skin-dimmed hover:bg-gray-200 hover:text-skin-muted;
-}
-
-.mobile-profile-menu-item {
-  @apply block font-sans px-4 py-2 text-base font-medium text-skin-dimmed hover:text-skin-muted hover:bg-gray-200;
-}
-
-.mobile-button {
-  @apply inline-flex items-center justify-center p-2 rounded-md text-skin-dimmed hover:text-skin-muted hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-inset focus:ring-skin-accented;
-}
+@import "tailwindcss/base";
+@import "../maquina.css";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";

data/app/assets/stylesheets/maquina.css

@@ -0,0 +1,114 @@
+/* Base maquina styles */
+
+:root {
+  --color-base: 31 27 54;
+  --color-accented: 37 99 235;
+  --color-inverted: 255 255 255;
+  --color-accented-hover: 59 130 246;
+  --color-muted: 55 65 81;
+  --color-dimmed: 75 85 99;
+  --color-error: 220 38 38;
+
+  --color-alternate: 219 90 186;
+  --color-alternate-1: 198 218 191;
+  --color-alternate-2: 23 24 59;
+
+  --color-border-base: 209 213 219;
+  --color-border-accented: 37 99 235;
+}
+
+.label {
+  @apply text-sm font-medium text-skin-muted;
+}
+
+.input {
+  @apply appearance-none rounded-md border border-skin-base px-3 py-2 placeholder-gray-400 shadow-sm focus:border-skin-accented focus:outline-none focus:ring-skin-accented sm:text-sm;
+}
+
+.link {
+  @apply font-medium text-skin-accented hover:text-skin-accented-hover;
+}
+
+.check {
+  @apply border-skin-base h-4 w-4 text-skin-accented focus:ring-skin-accented rounded;
+}
+
+.button {
+  @apply inline-flex justify-center py-2 px-4 border border-skin-base rounded-md shadow-sm text-sm font-medium text-skin-muted bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-skin-accented;
+}
+
+.select {
+  @apply block w-full rounded-md border-0 py-2 pl-3 pr-10 text-skin-base ring-1 ring-inset ring-gray-300 focus:ring-2 focus:ring-skin-accented sm:text-sm/6;
+}
+
+.control-error .label {
+  @apply text-skin-error;
+}
+
+.control-error .input {
+  @apply border-skin-error focus:border-skin-error focus:ring-skin-error;
+}
+
+.filter-option {
+  @apply mr-2 flex h-4 w-4 items-center justify-center rounded-sm border border-gray-400 opacity-50 text-white;
+}
+
+.filter-option[selected] {
+  @apply bg-skin-accented text-white border-0 opacity-100;
+}
+
+.help {
+  @apply mt-2 text-sm text-skin-dimmed;
+}
+
+.help-error {
+  @apply text-skin-error;
+}
+
+.button[disabled] {
+  @apply bg-gray-50 text-skin-dimmed cursor-default;
+}
+
+.button-accented {
+  @apply rounded-md border border-transparent bg-skin-accented py-2 px-4 text-sm font-medium text-skin-inverted shadow-sm hover:bg-skin-accented-hover focus:outline-none focus:ring-2 focus:ring-skin-accented focus:ring-offset-2;
+}
+
+input[type="search"] {
+  @apply block w-full rounded-md border border-skin-base pl-10 leading-5 placeholder-gray-400 focus:placeholder-gray-300 focus:outline-none focus:ring-1 focus:ring-skin-accented focus:border-skin-accented sm:text-sm;
+}
+
+.desktop-menu {
+  @apply hidden lg:ml-6 lg:flex lg:space-x-8;
+}
+
+.desktop-menu-item {
+  @apply font-sans uppercase border-transparent text-skin-dimmed underline-offset-4 decoration-2 hover:underline hover:decoration-skin-accented hover:text-skin-muted inline-flex items-center px-1 pt-1 text-sm font-medium;
+}
+
+.desktop-menu-item__active {
+  @apply decoration-skin-accented underline text-skin-base;
+}
+
+.mobile-menu {
+  @apply pt-2 pb-3 space-y-1;
+}
+
+.mobile-menu-item {
+  @apply font-sans border-transparent text-skin-dimmed hover:bg-gray-200 hover:border-gray-300 hover:text-skin-muted block pl-3 pr-4 py-2 border-l-4 text-base font-medium;
+}
+
+.mobile-menu-item__active {
+  @apply bg-skin-accented-hover border-skin-accented text-skin-accented hover:text-skin-accented hover:bg-skin-accented-hover hover:border-skin-accented;
+}
+
+.desktop-profile-menu-item {
+  @apply block w-full text-left font-sans px-4 py-2 text-sm text-skin-dimmed hover:bg-gray-200 hover:text-skin-muted;
+}
+
+.mobile-profile-menu-item {
+  @apply block font-sans px-4 py-2 text-base font-medium text-skin-dimmed hover:text-skin-muted hover:bg-gray-200;
+}
+
+.mobile-button {
+  @apply inline-flex items-center justify-center p-2 rounded-md text-skin-dimmed hover:text-skin-muted hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-inset focus:ring-skin-accented;
+}

data/app/controllers/concerns/maquina/authenticate.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # A Rails controller concern that handles user authentication.
+  # Provides methods for checking authentication status, managing sessions,
+  # and controlling access to actions.
+  #
+  # == Usage
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Maquina::Authenticate
+  #   end
+  #
   module Authenticate
     extend ActiveSupport::Concern
 
@@ -10,24 +21,41 @@ module Maquina
     end
 
     class_methods do
+      ##
+      # Skips authentication requirement for specified actions
       def allow_unauthenticated_access(...)
         skip_before_action(:require_authentication, ...)
       end
     end
 
+    ##
+    # Returns whether there is a signed in user
+    #
+    #   authenticated? # => true
     def authenticated?
       Maquina::Current.signed_in?
     end
     alias_method :signed_in?, :authenticated?
 
+    ##
+    # Returns the currently signed in user or nil
+    #
+    #   current_user # => #<User id: 1, email: "user@example.com">
     def current_user
       Maquina::Current.user
     end
 
+    ##
+    # Returns the URL to redirect to after successful authentication
+    #
+    #   after_authentication_url # => "http://example.com/dashboard"
     def after_authentication_url
       session.delete(:return_to_after_authenticating) || root_url
     end
 
+    ##
+    # Ensures user is authenticated before proceeding.
+    # Redirects to login if no valid session exists.
     def require_authentication
       load_session || request_authentication
     end
@@ -57,7 +85,7 @@ module Maquina
         )
         .find_by(id: active_session_id)
 
-      return if active_session.blank?
+      return if active_session.blank? || active_session.expired?
 
       Maquina::Current.active_session = active_session
     end

data/app/controllers/concerns/maquina/index.rb

@@ -1,6 +1,34 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # The Index concern provides standardized index action functionality for Rails controllers.
+  # It includes pagination, authorization, searching, and sorting capabilities.
+  #
+  # === Features
+  # * Automatic pagination using Pagy
+  # * Policy-based authorization support
+  # * Full-text search integration (when model supports it)
+  # * Default sorting by updated_at
+  # * HTML and JSON response formats
+  # * Customizable scope through block parameter
+  #
+  # === Dependencies
+  # * {Pagy::Backend}[https://ddnexus.github.io/pagy/api/backend]
+  # * Policy class (optional)
+  # * Model must respond to +full_search+ if searching is used
+  #
+  # === Usage
+  #   class UsersController < ApplicationController
+  #     include Maquina::Index
+  #
+  #     def index
+  #       index! do |scope|
+  #         scope.includes(:organization)
+  #       end
+  #     end
+  #   end
+  #
   module Index
     extend ActiveSupport::Concern
     include Pagy::Backend
@@ -10,11 +38,13 @@ module Maquina
         authorize! with: policy_class if policy_class.present?
 
         @collection ||= begin
-          scope = resource_class.order(updated_at: :desc)
+          scope = order_by(resource_class)
           scope = authorized_scope(scope) if policy_class.present?
 
           search_value = params[:q]&.strip
-          scope = scope.search_full(search_value) if search_value.present? && resource_class.searchable?
+          scope = scope.full_search(search_value) if search_value.present? && resource_class.searchable?
+
+          scope = filter_by(scope) if filters.any?
 
           scope = yield(scope) if block.present?
 
@@ -29,5 +59,54 @@ module Maquina
       end
       alias_method :index!, :index
     end
+
+    protected
+
+    ##
+    # Applies query parameters as filters to the given scope
+    #
+    # scope:: The base ActiveRecord::Relation to filter
+    # Returns:: The filtered ActiveRecord::Relation
+    #
+    def filter_by(scope)
+      filters.each_pair do |field, options|
+        if params[field].present?
+          scope = scope.where(field => params[field])
+        end
+      end
+
+      scope
+    end
+
+    ##
+    # Orders records based on order and direction parameters
+    #
+    # Returns scope ordered by updated_at desc if:
+    # * order parameter is blank
+    # * order attribute is not in sortable list
+    # * direction is not asc/desc
+    #
+    # scope:: The base ActiveRecord::Relation to order
+    # Returns:: The ordered ActiveRecord::Relation
+    #
+    def order_by(scope)
+      direction = ["asc", "desc"].include?(params[:dir]) ? params[:dir] : nil
+      attribute = params[:order]&.to_sym
+
+      return scope.order(updated_at: :desc) if attribute.blank? || !sortable.include?(attribute) || direction.blank?
+
+      attribute, direction = before_order_by(attribute, direction)
+      scope.order(attribute => direction)
+    end
+
+    # Hook method called before applying sort order. Override in controller to customize ordering behavior.
+    #
+    # attribute:: The Symbol attribute to sort by
+    # direction:: The String sort direction ("asc" or "desc")
+    # Returns:: Array containing the modified attribute and direction
+    #
+    def before_order_by(attribute, direction)
+      [attribute, direction]
+    end
   end
 end