crud_components 0.1.0

data/lib/crud_components.rb

@@ -0,0 +1,160 @@
+require 'bigdecimal'
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/date/calculations'
+require 'active_support/core_ext/date_and_time/calculations'
+require 'active_support/core_ext/integer/time'
+
+module CrudComponents
+  # The query params the gem owns (filters are top-level params named after the
+  # field, so a field can't share these names). Declaring such an attribute
+  # raises in the Builder rather than silently colliding with sort/pagination.
+  RESERVED_PARAMS = %w[q sort dir page per cols].freeze
+
+  # Sentinel filter value meaning "the column is NULL" (boolean/enum filters on
+  # nullable columns offer it as a "not set" choice). Improbable as a real
+  # value, so it never collides with a genuine enum key or boolean string.
+  NULL_FILTER_VALUE = '__null__'.freeze
+end
+
+require_relative 'crud_components/version'
+require_relative 'crud_components/errors'
+require_relative 'crud_components/config'
+require_relative 'crud_components/permission_context'
+require_relative 'crud_components/like_spec'
+require_relative 'crud_components/where_like'
+require_relative 'crud_components/fields/base'
+require_relative 'crud_components/fields/string_field'
+require_relative 'crud_components/fields/text_field'
+require_relative 'crud_components/fields/numeric_field'
+require_relative 'crud_components/fields/date_field'
+require_relative 'crud_components/fields/boolean_field'
+require_relative 'crud_components/fields/enum_field'
+require_relative 'crud_components/fields/json_field'
+require_relative 'crud_components/fields/attachment_field'
+require_relative 'crud_components/fields/belongs_to_field'
+require_relative 'crud_components/fields/has_many_field'
+require_relative 'crud_components/fields/computed_field'
+require_relative 'crud_components/fields/path_field'
+require_relative 'crud_components/fields/dynamic_field'
+require_relative 'crud_components/dynamic_column'
+require_relative 'crud_components/action'
+require_relative 'crud_components/fieldset'
+require_relative 'crud_components/builder'
+require_relative 'crud_components/structure'
+require_relative 'crud_components/model'
+require_relative 'crud_components/query'
+
+module CrudComponents
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def structure_for(model)
+      Structure.for(model)
+    end
+
+    # Safe case-insensitive contains-match on any relation, using the same
+    # escaped-ILIKE machinery as `filter like:` / `search_in` — so you never
+    # hand-write `where("col LIKE ?", "%#{value}%")` (which forgets to escape the
+    # user's `%`/`_`). The scope handed to a filter/search block already carries
+    # `#where_like`; this module function is for the relations you build yourself,
+    # e.g. a subquery on another model:
+    #
+    #   filter: ->(scope, value) {
+    #     ids = CrudComponents.where_like(PropertyValue.where(definition: prop), :value, value)
+    #     scope.where(id: ids.select(:subject_id))
+    #   }
+    #
+    # `spec` is a {LikeSpec} spec (`:value`, `%i[a b]`, `{ assoc: :col }`).
+    def where_like(relation, spec, value)
+      LikeSpec.apply(relation, spec, value)
+    end
+
+    # The column-picker selection from a request's params: the ordered list of
+    # column names the user ticked, or nil when the picker wasn't submitted.
+    # Honors `param_prefix:` (match it to the picker's). Persist it however you
+    # like, then feed it back via `picked_columns:`.
+    #
+    #   cols = CrudComponents.selected_columns(params)
+    #   current_user.update!(book_columns: cols) if cols
+    #
+    # A block runs only when a selection was submitted, and receives the list:
+    #
+    #   CrudComponents.selected_columns(params) { |cols| current_user.update!(book_columns: cols) }
+    #
+    # Accepts both the no-JS `cols[]=a&cols[]=b` array and the comma-joined
+    # `cols=a,b` the crud-columns controller submits.
+    def selected_columns(params, param_prefix: nil)
+      key = param_prefix ? "#{param_prefix}_cols" : 'cols'
+      raw = params[key] || params[key.to_sym]
+      list = raw.is_a?(Array) ? raw : raw.is_a?(String) ? raw.split(',') : nil
+      names = list&.map { |n| n.to_s.strip }&.reject(&:blank?)
+      names = nil if names.nil? || names.empty?
+      yield names if block_given? && names
+      names
+    end
+
+    # Whether non-image attachment previews (e.g. a PDF's first page) can
+    # actually be generated here. Beyond a previewer binary (poppler/ffmpeg,
+    # which `previewable?` already checks), processing needs `image_processing`
+    # plus the configured variant backend's gem (ruby-vips or mini_magick).
+    # When any is missing, the renderer shows an icon + filename rather than a
+    # preview that would 500 at processing time.
+    # @api private
+    def previews_available?
+      return @previews_available if defined?(@previews_available)
+
+      @previews_available = begin
+        require 'image_processing'
+        processor = defined?(ActiveStorage) ? ActiveStorage.variant_processor : :vips
+        require(processor.to_s == 'mini_magick' ? 'mini_magick' : 'vips')
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    # The strong-params permit list for a model's derived form — the same
+    # field metadata the form renders from, so the two can't drift. Use in a
+    # controller:
+    #   params.require(:book)
+    #         .permit(*CrudComponents.permitted_attributes(Book, action: :update,
+    #                                                       ability: current_ability))
+    def permitted_attributes(model, action: :update, ability: nil)
+      Structure.for(model).permitted_params(action, PermissionContext.new(ability))
+    end
+
+    # Resolve a bulk-action selection from request params into a relation. The
+    # row checkboxes submit `selected[]=<identify_by>` (a slug array; a comma
+    # string is also accepted).
+    #
+    # Pass the same authorized scope you'd render — selection narrows *within*
+    # it, so a tampered slug can never reach a row outside it:
+    #   CrudComponents.selected(@books, params).destroy_all   # @books already scoped
+    # A model class also works when you don't scope (acts on the whole table):
+    #   CrudComponents.selected(Book, params)
+    def selected(scope, params, param: :selected)
+      model = scope.respond_to?(:klass) ? scope.klass : scope
+      values = Array(params[param]).flat_map { |v| v.to_s.split(',') }.map(&:strip).reject(&:blank?)
+      scope.where(Structure.for(model).identify_by => values)
+    end
+
+    # The gem's stylesheet (the column-picker float styles), read once from the
+    # packaged file. Backs the `crud_components_styles` helper, which inlines it;
+    # the same file is also linkable via `stylesheet_link_tag "crud_components"`
+    # on hosts whose asset pipeline serves engine assets.
+    def bundled_css
+      @bundled_css ||= File.read(File.expand_path('../app/assets/stylesheets/crud_components.css', __dir__))
+    end
+  end
+end
+
+require_relative 'crud_components/engine' if defined?(Rails::Engine)

data/lib/generators/crud_components/install/install_generator.rb

@@ -0,0 +1,43 @@
+module CrudComponents
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates the CrudComponents initializer and copies the optional ' \
+           'Stimulus controllers (filter niceties + habtm token/chip picker).'
+
+      def create_initializer
+        copy_file 'initializer.rb', 'config/initializers/crud_components.rb'
+      end
+
+      def copy_stimulus_controllers
+        copy_file 'crud_filter_controller.js', 'app/javascript/controllers/crud_filter_controller.js'
+        copy_file 'crud_multiselect_controller.js', 'app/javascript/controllers/crud_multiselect_controller.js'
+        copy_file 'crud_select_controller.js', 'app/javascript/controllers/crud_select_controller.js'
+        copy_file 'crud_columns_controller.js', 'app/javascript/controllers/crud_columns_controller.js'
+        say <<~NOTE
+
+          Load the gem's stylesheet (it makes the column picker float; everything
+          else is plain Bootstrap). Either is fine:
+            - layout <head>:           <%= crud_components_styles %>   (works under any
+              asset setup — cssbundling/sass, importmap, sprockets, propshaft)
+            - or, asset-pipeline hosts: <%= stylesheet_link_tag "crud_components" %>
+
+          The Stimulus controllers are optional — everything works without them.
+          - crud-filter: strip empty params on submit + auto-submit inline selects.
+          - crud-multiselect: turn a habtm `<select multiple>` into a chips + add picker.
+          - crud-select: "select all" / per-group checkboxes + a live count for bulk actions.
+          - crud-columns: drag-to-reorder the column picker (ticking columns works without it).
+          Register them (stimulus-rails with importmap does this automatically via
+          controllers/index.js; otherwise):
+
+            application.register("crud-filter", CrudFilterController)
+            application.register("crud-multiselect", CrudMultiselectController)
+            application.register("crud-select", CrudSelectController)
+            application.register("crud-columns", CrudColumnsController)
+
+        NOTE
+      end
+    end
+  end
+end

data/lib/generators/crud_components/install/templates/crud_columns_controller.js

@@ -0,0 +1,76 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Optional progressive enhancement for the CrudComponents column picker:
+// - drag the rows to reorder columns
+// - on submit, collapse the `cols[]=a&cols[]=b` array into a single `cols=a,b`
+//   for a prettier, shareable URL (the server reads both forms)
+// Without this controller the picker still works — ticked checkboxes submit
+// `cols[]` in their listed order; you just can't reorder by dragging, and the
+// URL keeps the repeated `cols[]` form. Submission order = DOM order of the <li>s.
+export default class extends Controller {
+  static targets = ["list", "item"]
+
+  // Rewrite the checked cols[] boxes into one comma-joined hidden field per param
+  // group (handles param_prefix). Mirrors crud-filter#clean: mutate during the
+  // submit event so the browser serializes the rewritten form, then restore
+  // shortly after in case the navigation was cancelled.
+  clean(event) {
+    const form = event.target
+    this.injected = []
+    this.disabledBoxes = []
+    const groups = new Map() // base name (without []) -> [values] in DOM order
+
+    for (const box of form.querySelectorAll('input[type=checkbox][name$="[]"]')) {
+      const base = box.name.slice(0, -2)
+      this.disabledBoxes.push(box)
+      box.disabled = true // drop the array form from this submit
+      if (box.checked) (groups.get(base) || groups.set(base, []).get(base)).push(box.value)
+    }
+    for (const [base, values] of groups) {
+      const hidden = document.createElement("input")
+      hidden.type = "hidden"
+      hidden.name = base
+      hidden.value = values.join(",")
+      form.appendChild(hidden)
+      this.injected.push(hidden)
+    }
+    setTimeout(() => {
+      this.injected.forEach((n) => n.remove())
+      this.disabledBoxes.forEach((b) => (b.disabled = false))
+      this.injected = this.disabledBoxes = []
+    }, 500)
+  }
+
+  connect() {
+    this.dragging = null
+  }
+
+  itemTargetConnected(item) {
+    item.addEventListener("dragstart", (e) => this.start(e, item))
+    item.addEventListener("dragover", (e) => this.over(e, item))
+    item.addEventListener("dragend", () => this.end(item))
+  }
+
+  start(event, item) {
+    this.dragging = item
+    item.classList.add("is-dragging")
+    event.dataTransfer.effectAllowed = "move"
+  }
+
+  over(event, item) {
+    event.preventDefault()
+    if (!this.dragging || this.dragging === item) return
+    const rect = item.getBoundingClientRect()
+    const after = event.clientY - rect.top > rect.height / 2
+    item.parentNode.insertBefore(this.dragging, after ? item.nextSibling : item)
+  }
+
+  end(item) {
+    item.classList.remove("is-dragging")
+    this.dragging = null
+  }
+
+  // A checkbox toggled with nothing else to do — kept so the markup's
+  // data-action has a handler and future enhancements have a hook.
+  toggle() {}
+}

data/lib/generators/crud_components/install/templates/crud_filter_controller.js

@@ -0,0 +1,32 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Optional progressive enhancement for CrudComponents filter forms:
+// - strips empty inputs on submit (clean, shareable URLs)
+// - auto-submits selects in the inline filter row (wired via data-action)
+// Everything works without this controller — plain GET forms.
+export default class extends Controller {
+  static targets = ["form"]
+
+  clean() {
+    this.cleaned = []
+    for (const element of this.form.elements) {
+      if (element.name && element.value === "" && !element.disabled) {
+        element.disabled = true
+        this.cleaned.push(element)
+      }
+    }
+    // Re-enable shortly after, in case the navigation was cancelled.
+    setTimeout(() => {
+      this.cleaned.forEach((element) => (element.disabled = false))
+      this.cleaned = []
+    }, 500)
+  }
+
+  submit() {
+    this.form.requestSubmit()
+  }
+
+  get form() {
+    return this.hasFormTarget ? this.formTarget : this.element
+  }
+}

data/lib/generators/crud_components/install/templates/crud_multiselect_controller.js

@@ -0,0 +1,70 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Optional progressive enhancement for habtm/has_many form fields
+// (data-controller="crud-multiselect"): replaces a `<select multiple>` with a
+// chips-list (each removable with ×) + an "add" dropdown. The select stays in
+// the DOM as the hidden source of truth, so the form submits identically with
+// or without JavaScript.
+//
+// Good for sets up to a few hundred (all options live client-side). For very
+// large sets, render an autocomplete against your own endpoint instead — see
+// the docs (Forms / Extending).
+export default class extends Controller {
+  connect() {
+    this.select = this.element.matches("select[multiple]")
+      ? this.element
+      : this.element.querySelector("select[multiple]")
+    if (!this.select) return
+
+    this.select.style.display = "none"
+    this.chips = document.createElement("div")
+    this.chips.className = "d-flex flex-wrap gap-1 mb-1"
+    this.adder = document.createElement("select")
+    this.adder.className = "form-select"
+    this.adder.addEventListener("change", () => this.toggle(this.adder.value, true))
+    this.select.insertAdjacentElement("beforebegin", this.chips)
+    this.select.insertAdjacentElement("beforebegin", this.adder)
+    this.render()
+  }
+
+  get options() {
+    return Array.from(this.select.options)
+  }
+
+  render() {
+    this.chips.replaceChildren(
+      ...this.options.filter((o) => o.selected).map((o) => this.chip(o))
+    )
+    this.adder.replaceChildren(this.option("", "+ add…"))
+    this.options
+      .filter((o) => !o.selected)
+      .forEach((o) => this.adder.appendChild(this.option(o.value, o.text)))
+  }
+
+  chip(option) {
+    const chip = document.createElement("span")
+    chip.className = "badge text-bg-primary d-inline-flex align-items-center gap-1"
+    chip.textContent = option.text
+    const close = document.createElement("button")
+    close.type = "button"
+    close.className = "btn-close btn-close-white"
+    close.style.fontSize = ".6rem"
+    close.addEventListener("click", () => this.toggle(option.value, false))
+    chip.appendChild(close)
+    return chip
+  }
+
+  option(value, text) {
+    const opt = document.createElement("option")
+    opt.value = value
+    opt.text = text
+    return opt
+  }
+
+  toggle(value, selected) {
+    const option = this.options.find((o) => o.value === value)
+    if (!option) return
+    option.selected = selected
+    this.render()
+  }
+}

data/lib/generators/crud_components/install/templates/crud_select_controller.js

@@ -0,0 +1,35 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Optional progressive enhancement for selectable collections: a "select all"
+// (visible rows) and per-group master checkbox, plus a live "N selected" count.
+// The row checkboxes submit selected[] without this — it just spares the
+// clicking. The bulk-action buttons post the form regardless.
+export default class extends Controller {
+  static targets = ["row", "all", "group", "count", "button"]
+
+  connect() { this.update() }
+
+  toggleAll() {
+    this.rowTargets.forEach((row) => (row.checked = this.allTarget.checked))
+    this.update()
+  }
+
+  toggleGroup(event) {
+    const key = event.target.dataset.group
+    this.rowTargets.forEach((row) => {
+      if (row.dataset.group === key) row.checked = event.target.checked
+    })
+    this.update()
+  }
+
+  update() {
+    const count = this.rowTargets.filter((row) => row.checked).length
+    if (this.hasAllTarget) {
+      this.allTarget.checked = count > 0 && count === this.rowTargets.length
+      this.allTarget.indeterminate = count > 0 && count < this.rowTargets.length
+    }
+    if (this.hasCountTarget) this.countTarget.textContent = `${count} selected`
+    // disable the bulk-action buttons while nothing is selected
+    this.buttonTargets.forEach((button) => (button.disabled = count === 0))
+  }
+}

data/lib/generators/crud_components/install/templates/initializer.rb

@@ -0,0 +1,56 @@
+# CrudComponents — everything has a working default; uncomment to deviate.
+CrudComponents.configure do |config|
+  # belongs_to filter selects switch to a text input over the target's
+  # search_in beyond this many records:
+  # config.select_limit = 250
+
+  # Grouped collections (`group_by:`) open all groups below this row count, the
+  # first only above it:
+  # config.group_collapse_threshold = 50
+
+  # Icon names (no library prefix — paired with css.icon_prefix). Action glyphs
+  # are a name=>icon map (nil = no icon); file glyphs map an extension to a full
+  # icon name, with a fallback. Full key lists: Config::DEFAULT_ACTION_ICONS /
+  # Config::DEFAULT_FILE_ICONS.
+  # config.action_icons[:destroy] = 'trash-fill'
+  # config.file_icons['zip'] = 'file-earmark-zip'
+  # config.file_fallback_icon = 'file-earmark-text'
+
+  # Per-model icon (column-picker groups, association links, path-column cells),
+  # guessed from the model name unless a model declares `icon '…'`. Add your own
+  # mapping (key = singular underscored model name) or badge every model with a
+  # fallback. Full key list: Config::DEFAULT_MODEL_ICONS.
+  # config.model_icons['widget'] = 'box-seam'
+  # config.model_fallback_icon = 'box'   # default nil = no icon when unmapped
+
+  # CSS class map (Bootstrap 5 defaults). The full key list:
+  # CrudComponents::Config::DEFAULT_CSS  
+  # config.css.table = 'table align-middle'
+  # config.css.thead = ''
+  # config.css.filter_row = 'crud-filter-row'
+  # config.css.sort_link = 'text-reset text-decoration-none'
+  # config.css.actions_cell = 'text-end'
+  # config.css.button_group = 'btn-group btn-group-sm'
+  # config.css.button = 'btn btn-sm btn-outline-secondary'
+  # config.css.button_primary = 'btn btn-sm btn-primary'
+  # config.css.button_danger = 'btn btn-sm btn-outline-danger'
+  # config.css.pagination = 'pagination pagination-sm'  # footer pager (paginated relations)
+  # config.css.badge = 'badge text-bg-secondary'
+  # config.css.badge_muted = 'badge text-bg-light'
+  # config.css.input = 'form-control'
+  # config.css.input_sm = 'form-control form-control-sm'
+  # # named *_input to avoid OrderedOptions#select (Hash#select) collisions
+  # config.css.select_input = 'form-select'
+  # config.css.select_input_sm = 'form-select form-select-sm'
+  # config.css.form_label = 'form-label'
+  # config.css.filter_grid = 'row row-cols-1 g-2'
+  # config.css.input_group = 'input-group flex-nowrap'
+  # config.css.boolean_true = 'text-success'
+  # config.css.boolean_false = 'text-danger'
+  # config.css.muted = 'text-muted'
+  # icon font base + name prefix; 'fa fa-' for Font Awesome (icon names differ)
+  # config.css.icon_prefix = 'bi bi-'
+  # config.css.dl = 'row'
+  # config.css.dt = 'col-sm-3'
+  # config.css.dd = 'col-sm-9'
+end

data/lib/generators/crud_components/views/views_generator.rb

@@ -0,0 +1,14 @@
+module CrudComponents
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path('../../../../app/views/crud_components', __dir__)
+
+      desc 'Copies all CrudComponents partials into your app for editing — ' \
+           'a file at the same path wins over the gem version.'
+
+      def copy_views
+        directory '.', 'app/views/crud_components'
+      end
+    end
+  end
+end