labimotion 2.3.0.rc4 → 2.3.0.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf074c0e6f0eb9c3b52aec0dcde8e8c2a9b2f386027eae477a089e2ff19f4572
-  data.tar.gz: 6927c3bc49367aed7830fa2744769deb6fad51c4b24897da10531dab1cb235ce
+  metadata.gz: 57f6db758edf09de9105830d7a9f9cfda1270ac36bb6ee4351da8ab65b2ea2dc
+  data.tar.gz: 0e220ffc2a76645f8e82536cd592d7ee9eecd28e54073b408a602da019839e9f
 SHA512:
-  metadata.gz: 30cf888e8b21894ebcf8b9bc1b1b7618271a56b73678c5f83e3ce17b420a1f8452c16ecc7b073f3bd756edc33765316714a0247a623479505a4db54a8cc7c1ab
-  data.tar.gz: 6938831a6aa29266675e58aba6e092aadc5a1252b7df453376509fe38904a5254eb42a01b333a8954039c1fc7e5b9106ad234cc5a1b71ded6b1b8d0596dbb1a0
+  metadata.gz: f3f5ca1afdb69edbbf36f09834a04843d72d9b964db836719991a5d8b1acb10036cf4470f4ca1810bac6b629bc6908dc2ed5054127216ed9d6109b01d205ab07
+  data.tar.gz: cf72bfa7a774ef98e1474d5a4e3914304f940105137f18f05adb4b5675afdeab668e305386bda9ce1b842b2083005fc622c210d27c60b1005cfcba90c1eb2617

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # LabIMotion Changelog
 
+## [Unreleased]
+* Features and enhancements:
+  * Element variations can be exported to and imported from Excel (`.xlsx`). The exported workbook is itself the import template: `GET /api/v1/element_variations/:element_id/export` and `POST /api/v1/element_variations/:element_id/import`.
+  * The exported sheet carries the grid's grouped header -- group, sub-group and field rows, merged as the grid draws them -- above the hidden key and unit rows. Workbooks from the earlier single-row header still import.
+  * Import merges rows by uuid, so a sheet only updates the columns it carries; a row with a blank `Row ID` is added as a new variation.
+  * `number`, `integer` and `system-defined` columns accept numbers only. A cell holding anything else is cleared with a warning rather than stored as text, which also cleans up text those columns already hold.
+  * Import warnings name the cell they came from (`Cell I6: ...`), so the user can go straight to it in the spreadsheet.
+* Bug fixes:
+  * `fetch_for_user`: the shared-records branch joined `collection_shares` directly on the element model (an association that only exists on `Collection`), raising `ActiveRecord::ConfigurationError` — rescued into empty search results. Now joins through `collections`. Fixed for both the basic elements (`ElementFetchable`) and the generic element (`Labimotion::Element`), so `search_by_like` and `search_basic_by_like` return shared records again.
+* Dependencies:
+  * Added `roo` (~> 2.10) for reading the uploaded workbook.
+
 ## [2.0.0]
 > 2025-03-25
 * Features and enhancements:

data/lib/labimotion/apis/element_variation_api.rb

@@ -1,15 +1,39 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module Labimotion
   class ElementVariationAPI < Grape::API
+    XLSX_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+
     rescue_from ActiveRecord::RecordNotFound do
       error!('404 Element not found', 404)
     end
 
+    helpers do
+      def configure_xlsx_response(filename)
+        env['api.format'] = :binary
+        content_type XLSX_CONTENT_TYPE
+        encoded = URI.encode_www_form_component(filename)
+        header('Content-Disposition', "attachment; filename=\"#{filename}\"; filename*=UTF-8''#{encoded}")
+      end
+
+      def uploaded_xlsx_path!(file)
+        filename = file[:filename].to_s
+        error!('400 Bad Request - expected an .xlsx file', 400) unless filename.downcase.end_with?('.xlsx')
+
+        tempfile = file[:tempfile]
+        error!('400 Bad Request - upload is empty', 400) if tempfile.nil?
+
+        tempfile.path
+      end
+    end
+
     resource :element_variations do
       params do
         requires :element_id, type: Integer, desc: 'Generic element id'
       end
+      # rubocop:disable Metrics/BlockLength
       route_param :element_id do
         before do
           @element = Labimotion::Element.find(params[:element_id])
@@ -32,14 +56,45 @@ module Labimotion
 
           record = Labimotion::ElementVariation.find_or_initialize_by(element_id: @element.id)
           record.variations = params[:variations] || {}
-          if params.key?(:layout) && record.class.column_names.include?('layout')
-            record.layout = params[:layout] || {}
-          end
+          record.layout = params[:layout] || {} if params.key?(:layout) && record.class.column_names.include?('layout')
           record.save!
 
           present record, with: Labimotion::ElementVariationEntity, root: 'element_variation'
         end
+
+        desc 'Export element variations as an xlsx workbook'
+        get :export do
+          exporter = Labimotion::ExportElementVariations.new(@element, user: current_user)
+          configure_xlsx_response(exporter.filename)
+          exporter.read
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          error!("500 Internal Server Error: #{e.message}", 500)
+        end
+
+        desc 'Import element variations from an xlsx workbook produced by the export'
+        params do
+          requires :file, type: File, desc: 'xlsx file'
+        end
+        post :import do
+          error!('401 Unauthorized', 401) unless ElementPolicy.new(current_user, @element).update?
+
+          path = uploaded_xlsx_path!(params[:file])
+          importer = Labimotion::ImportElementVariations.new(@element, path)
+          record = importer.execute!
+
+          {
+            element_variation: Labimotion::ElementVariationEntity.represent(record),
+            warnings: importer.warnings
+          }
+        rescue Labimotion::ImportElementVariations::InvalidWorkbook => e
+          error!(e.message, 422)
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          error!("500 Internal Server Error: #{e.message}", 500)
+        end
       end
+      # rubocop:enable Metrics/BlockLength
     end
   end
 end

data/lib/labimotion/libs/element_variation_column_set.rb

@@ -0,0 +1,426 @@
+# frozen_string_literal: true
+
+require 'labimotion/utils/units'
+
+module Labimotion
+  ## ElementVariationColumnSet
+  # Resolves the ordered set of columns for an element's variations grid.
+  #
+  # Both ExportElementVariations and ImportElementVariations go through this
+  # class, so a workbook written by the exporter is always readable by the
+  # importer. The ordering mirrors the React grid
+  # (GenericElementVariationsColumnDefs.js): driven by the stored layout when
+  # there is one, otherwise inferred from the variation data itself -- the same
+  # fallback the frontend applies when it loads a record with an empty layout.
+  class ElementVariationColumnSet
+    UUID_KEY = '__uuid'
+    NAME_KEY = '__variation'
+    ANALYSES_FIELD = '__analyses__'
+
+    # Mirrors Labimotion::Prop::LAYERS / ::FIELDS. Held locally because
+    # requiring `labimotion/utils/prop` here would race the gem's autoload.
+    LAYERS = 'layers'
+    FIELDS = 'fields'
+
+    GROUPS = %w[properties metadata segments].freeze
+    GROUP_LABELS = {
+      'properties' => 'Properties',
+      'metadata' => 'Metadata',
+      'segments' => 'Segments'
+    }.freeze
+    METADATA_FIELDS = %w[notes analyses group].freeze
+    METADATA_LABELS = {
+      'notes' => 'Notes',
+      'analyses' => 'Analyses (IDs)',
+      'group' => 'Group'
+    }.freeze
+
+    # Mirrors the field-type allowlist chem-generic-ui applies when it offers
+    # columns. `select-multi` deliberately has no Labimotion::FieldType constant.
+    COLUMN_FIELD_TYPES = %w[
+      integer number select system-defined text date datetime select-multi
+    ].freeze
+
+    # `label` is the leaf header only. `group` / `sub_group` carry the two header
+    # levels above it, so the exporter can rebuild the grid's banded header.
+    # `sub_group_key` disambiguates two sub-groups that happen to share a label.
+    Column = Struct.new(
+      :key, :label, :unit, :kind, :field_type, :group, :sub_group, :sub_group_key,
+      keyword_init: true
+    )
+
+    class << self
+      def build(element, variation, segment_klasses: nil)
+        new(element, variation, segment_klasses: segment_klasses).columns
+      end
+
+      def encode_property_key(layer_key, field_key)
+        "layer#{layer_key}field#{field_key}"
+      end
+
+      def decode_property_key(key)
+        match = key.to_s.match(/\Alayer(.+?)field(.+)\z/m)
+        return nil unless match
+
+        { layer_key: match[1], field_key: match[2] }
+      end
+
+      def analyses_property_key?(key)
+        decoded = decode_property_key(key)
+        !decoded.nil? && decoded[:field_key] == ANALYSES_FIELD
+      end
+    end
+
+    def initialize(element, variation, segment_klasses: nil)
+      @element = element
+      @variations = variation.respond_to?(:variations_hash) ? variation.variations_hash : {}
+      @layout = variation.respond_to?(:layout_hash) ? variation.layout_hash : {}
+      @segment_klasses = segment_klasses
+    end
+
+    attr_reader :element, :variations, :layout
+
+    def columns
+      @columns ||= begin
+        cols = [
+          Column.new(key: UUID_KEY, label: 'Row ID', unit: '', kind: :uuid, field_type: nil),
+          Column.new(key: NAME_KEY, label: 'Variation', unit: '', kind: :name, field_type: nil)
+        ]
+        group_order.each { |group| cols.concat(columns_for_group(group)) }
+        cols
+      end
+    end
+
+    def lookup(key)
+      @lookup ||= columns.each_with_object({}) { |col, acc| acc[col.key] = col }
+      @lookup[key]
+    end
+
+    # Variation rows in the grid's display order: layout rowOrder first, then
+    # anything the layout does not mention, uuid-sorted (as `sortedRows` does).
+    def rows
+      seen = {}
+      ordered = []
+      Array(layout['rowOrder']).each do |uuid|
+        row = variations[uuid.to_s]
+        next unless row.is_a?(Hash)
+
+        ordered << row
+        seen[uuid.to_s] = true
+      end
+      remaining = variations.reject { |uuid, row| seen[uuid.to_s] || !row.is_a?(Hash) }
+      ordered + remaining.values.sort_by { |row| row['uuid'].to_s }
+    end
+
+    def segment_klasses
+      @segment_klasses ||= Labimotion::SegmentKlass.where(element_klass_id: element.element_klass_id).to_a
+    end
+
+    def segment_klass(klass_id)
+      @segment_klass_index ||= segment_klasses.each_with_object({}) do |klass, acc|
+        acc[klass.id.to_s] = klass
+      end
+      @segment_klass_index[klass_id.to_s]
+    end
+
+    private
+
+    def columns_for_group(group)
+      case group
+      when 'properties' then property_columns
+      when 'metadata' then metadata_columns
+      when 'segments' then segment_columns
+      else []
+      end
+    end
+
+    def group_order
+      stored = Array(layout['groupOrder']).select { |group| GROUPS.include?(group) }
+      stored + (GROUPS - stored)
+    end
+
+    # ---- properties -------------------------------------------------------
+
+    # Grouped by layer, each layer's fields followed by its "Link Analyses"
+    # column -- the leaf order buildColumnDefs produces.
+    def property_columns
+      analysis_layers = selected_analysis_layers
+      property_layers.flat_map do |layer_key, layer|
+        next layer[:columns] unless analysis_layers.include?(layer_key)
+
+        layer[:columns] + [analyses_layer_column(layer_key, layer[:label])]
+      end
+    end
+
+    # layer_key => { label:, columns: }, in the grid's layer order: layers
+    # holding a selected field first, then layers selected for analyses only.
+    def property_layers
+      layers = {}
+      selected_property_keys.each do |property_key|
+        option = property_options[property_key]
+        next if option.nil?
+
+        layer = ensure_property_layer(layers, option['layerKey'], option['layerLabel'])
+        layer[:columns] << property_column(property_key, option, layer[:label])
+      end
+      selected_analysis_layers.each do |layer_key|
+        ensure_property_layer(layers, layer_key, layer_labels[layer_key.to_s])
+      end
+      layers
+    end
+
+    def ensure_property_layer(layers, layer_key, layer_label)
+      key = layer_key.to_s
+      layers[key] ||= { label: presence(layer_label) || key, columns: [] }
+    end
+
+    def property_column(property_key, option, layer_label)
+      unit = unit_for("prop:#{property_key}", option, inferred_property_unit(property_key))
+      Column.new(
+        key: "prop:#{property_key}",
+        label: with_unit(option['fieldLabel'], unit),
+        unit: unit,
+        kind: :property,
+        field_type: option['type'],
+        group: GROUP_LABELS['properties'],
+        sub_group: layer_label,
+        sub_group_key: option['layerKey'].to_s
+      )
+    end
+
+    def analyses_layer_column(layer_key, layer_label)
+      Column.new(
+        key: "prop:#{self.class.encode_property_key(layer_key, ANALYSES_FIELD)}",
+        label: 'Link Analyses (IDs)',
+        unit: '',
+        kind: :property,
+        field_type: ANALYSES_FIELD,
+        group: GROUP_LABELS['properties'],
+        sub_group: layer_label,
+        sub_group_key: layer_key.to_s
+      )
+    end
+
+    def selected_property_keys
+      stored = Array(layout['selectedPropertyKeys']).map(&:to_s)
+      return stored unless stored.empty?
+
+      keys_from_data.reject { |key| self.class.analyses_property_key?(key) }
+    end
+
+    def selected_analysis_layers
+      stored = Array(layout['selectedAnalysisLayers']).map(&:to_s)
+      return stored unless stored.empty?
+
+      keys_from_data.filter_map do |key|
+        decoded = self.class.decode_property_key(key)
+        decoded[:layer_key] if decoded && decoded[:field_key] == ANALYSES_FIELD
+      end.uniq
+    end
+
+    def keys_from_data
+      @keys_from_data ||= variations.values.flat_map do |row|
+        row.is_a?(Hash) ? (row['properties'] || {}).keys : []
+      end.uniq
+    end
+
+    def inferred_property_unit(key)
+      variations.each_value do |row|
+        next unless row.is_a?(Hash)
+
+        cell = (row['properties'] || {})[key]
+        return cell['unit'].to_s if cell.is_a?(Hash) && !cell['unit'].to_s.empty?
+      end
+      nil
+    end
+
+    # ---- metadata ---------------------------------------------------------
+
+    # Metadata leaves hang straight off the group, as they do in the grid: no
+    # sub_group, so the exporter spans their header down a row.
+    def metadata_columns
+      selected_metadata_keys.map do |field|
+        Column.new(
+          key: "meta:#{field}",
+          label: METADATA_LABELS[field] || field,
+          unit: '',
+          kind: :metadata,
+          field_type: field,
+          group: GROUP_LABELS['metadata']
+        )
+      end
+    end
+
+    def selected_metadata_keys
+      stored = Array(layout['selectedMetadataKeys']).map(&:to_s)
+      stored.empty? ? METADATA_FIELDS.dup : stored
+    end
+
+    # ---- segments ---------------------------------------------------------
+
+    def segment_columns
+      selected_segment_ids.flat_map do |klass_id|
+        klass = segment_klass(klass_id)
+        segment_label = klass ? (klass.label || "Segment #{klass_id}") : "Segment #{klass_id}"
+        options = segment_field_options(klass_id)
+
+        selected_segment_fields(klass_id).filter_map do |field_key|
+          option = options[field_key]
+          next if option.nil?
+
+          unit = unit_for("seg:#{klass_id}:#{field_key}", option, nil)
+          Column.new(
+            key: "seg:#{klass_id}:#{field_key}",
+            label: with_unit(option['fieldLabel'], unit),
+            unit: unit,
+            kind: :segment,
+            field_type: option['type'],
+            group: GROUP_LABELS['segments'],
+            sub_group: segment_label,
+            sub_group_key: klass_id.to_s
+          )
+        end
+      end
+    end
+
+    def selected_segment_ids
+      stored = Array(layout['selectedSegmentIds']).map(&:to_s)
+      return stored unless stored.empty?
+
+      variations.values.flat_map do |row|
+        row.is_a?(Hash) ? (row['segments'] || {}).keys.map(&:to_s) : []
+      end.uniq
+    end
+
+    def selected_segment_fields(klass_id)
+      stored = layout['selectedSegmentFields']
+      if stored.is_a?(Hash)
+        keys = stored[klass_id.to_s] || stored[klass_id.to_i]
+        return Array(keys).map(&:to_s) unless keys.nil?
+      end
+
+      variations.values.flat_map do |row|
+        next [] unless row.is_a?(Hash)
+
+        (row.dig('segments', klass_id.to_s) || {}).keys.map(&:to_s)
+      end.uniq
+    end
+
+    def segment_field_options(klass_id)
+      @segment_field_options ||= {}
+      @segment_field_options[klass_id.to_s] ||= begin
+        klass = segment_klass(klass_id)
+        options = {}
+        each_layer_field(release_of(klass)) do |_layer_key, _layer_label, field|
+          options[field['field'].to_s] ||= field_option(field)
+        end
+        options
+      end
+    end
+
+    # ---- shared schema walking -------------------------------------------
+
+    def property_options
+      @property_options ||= begin
+        options = {}
+        each_layer_field(element_klass_release) do |layer_key, layer_label, field|
+          key = self.class.encode_property_key(layer_key, field['field'])
+          options[key] = field_option(field).merge('layerKey' => layer_key, 'layerLabel' => layer_label)
+        end
+        options
+      end
+    end
+
+    def layer_labels
+      @layer_labels ||= begin
+        layers = element_klass_release[LAYERS] || {}
+        layers.each_with_object({}) do |(layer_key, layer), acc|
+          acc[layer_key.to_s] = layer['label'] || layer_key.to_s
+        end
+      end
+    end
+
+    def element_klass_release
+      @element_klass_release ||= begin
+        klass = element.respond_to?(:element_klass) ? element.element_klass : nil
+        release = release_of(klass)
+        release.empty? ? release_of(element) : release
+      end
+    end
+
+    def release_of(record)
+      return {} if record.nil? || !record.respond_to?(:properties_release)
+
+      release = record.properties_release
+      release.is_a?(Hash) ? release : {}
+    end
+
+    def each_layer_field(release)
+      layers = release[LAYERS] || {}
+      layers.each do |layer_key, layer|
+        next unless layer.is_a?(Hash)
+
+        layer_label = layer['label'] || layer_key.to_s
+        Array(layer[FIELDS]).each do |field|
+          next unless field.is_a?(Hash) && !field['field'].to_s.empty?
+          next unless COLUMN_FIELD_TYPES.include?(field['type'].to_s)
+
+          yield(layer_key.to_s, layer_label, field)
+        end
+      end
+    end
+
+    def field_option(field)
+      label = field['label'].to_s.empty? ? field['field'].to_s : field['label'].to_s
+      {
+        'fieldKey' => field['field'].to_s,
+        'fieldLabel' => label,
+        'type' => field['type'].to_s,
+        'defaultUnit' => default_unit(field)
+      }
+    end
+
+    # ---- units ------------------------------------------------------------
+
+    # The grid stores unit *keys* (`C`, `mm_s2`), never the display labels --
+    # some of which carry HTML (`mm/s<sup>2</sup>`). Keep the key: it is what a
+    # round-trip must preserve.
+    def field_units(field)
+      quantity = field['option_layers'] || field['generic_quantity']
+      return [] if quantity.to_s.empty?
+
+      config = Labimotion::Units::FIELDS.find { |entry| entry[:field] == quantity }
+      return [] unless config
+
+      Array(config[:units]).filter_map { |unit| unit[:key]&.to_s }
+    end
+
+    def default_unit(field)
+      units = field_units(field)
+      return '' if units.empty?
+
+      value_system = field['value_system'].to_s
+      value_system.empty? ? units.first : value_system
+    end
+
+    def unit_for(column_key, option, inferred)
+      stored = column_units[column_key]
+      return stored.to_s unless stored.to_s.empty?
+      return inferred.to_s unless inferred.to_s.empty?
+
+      option['defaultUnit'].to_s
+    end
+
+    def column_units
+      @column_units ||= layout['columnUnits'].is_a?(Hash) ? layout['columnUnits'] : {}
+    end
+
+    def with_unit(label, unit)
+      unit.to_s.empty? ? label : "#{label} [#{unit}]"
+    end
+
+    def presence(value)
+      value.to_s.empty? ? nil : value.to_s
+    end
+  end
+end

data/lib/labimotion/libs/element_variation_header.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'caxlsx'
+
+module Labimotion
+  ## ElementVariationHeader
+  # Turns an ordered column set into the banded header the React grid draws:
+  #
+  #   row 1  group      Properties                  | Metadata        | Segments
+  #   row 2  sub-group  Conditions                  | Notes | Group   | My Segment
+  #   row 3  leaf       Temperature [C] | Solvent   |       |         | Mass [g]
+  #
+  # Adjacent columns sharing a header are merged across, and a header with no
+  # level beneath it -- the identity columns, and the metadata leaves, which hang
+  # straight off their group -- is merged down to the leaf row. That is exactly
+  # what ag-grid renders for the same columns.
+  #
+  # `rows` are the three cell arrays; `merges` the ranges to hand to Axlsx.
+  class ElementVariationHeader
+    ROWS = 3
+
+    def initialize(columns)
+      @columns = columns
+    end
+
+    attr_reader :columns
+
+    def rows
+      plan[:rows]
+    end
+
+    def merges
+      plan[:merges]
+    end
+
+    private
+
+    def plan
+      @plan ||= build
+    end
+
+    def build
+      @rows = Array.new(ROWS) { Array.new(columns.length, '') }
+      @merges = []
+
+      runs(columns.map(&:group)).each { |run| place_group(run) }
+      runs(columns.map { |column| sub_group_key(column) }).each { |run| place_sub_group(run) }
+
+      { rows: @rows, merges: @merges }
+    end
+
+    def place_group(run)
+      # No group at all: an identity column, spanning the whole header.
+      return span_down(run, 0) if blank?(run[:key])
+
+      span_across(run, 0, run[:key])
+    end
+
+    def place_sub_group(run)
+      return if run[:key].nil?
+
+      sub_group = columns[run[:first]].sub_group
+      # No sub-group: a metadata leaf, spanning the rows below its group.
+      return span_down(run, 1) if blank?(sub_group)
+
+      span_across(run, 1, sub_group)
+      fill(run, 2)
+    end
+
+    # One cell per column, each merged down to the leaf row.
+    def span_down(run, row)
+      fill(run, row)
+      column_range(run).each { |index| merge(index, row, index, ROWS - 1) }
+    end
+
+    # A single cell carrying `text` across the whole run.
+    def span_across(run, row, text)
+      @rows[row][run[:first]] = text
+      merge(run[:first], row, run[:last], row) unless run[:last] == run[:first]
+    end
+
+    def fill(run, row)
+      column_range(run).each { |index| @rows[row][index] = columns[index].label }
+    end
+
+    def column_range(run)
+      (run[:first]..run[:last])
+    end
+
+    def merge(from_column, from_row, to_column, to_row)
+      @merges << [cell_ref(from_column, from_row), cell_ref(to_column, to_row)]
+    end
+
+    def cell_ref(column_index, row_index)
+      "#{Axlsx.col_ref(column_index)}#{row_index + 1}"
+    end
+
+    # Keyed on the sub-group *key*, not its label: two layers may share a label.
+    def sub_group_key(column)
+      blank?(column.group) ? nil : [column.group, column.sub_group_key]
+    end
+
+    # Contiguous columns sharing a header key.
+    def runs(keys)
+      keys.each_with_index.with_object([]) do |(key, index), acc|
+        last = acc.last
+        if last && last[:key] == key
+          last[:last] = index
+        else
+          acc << { key: key, first: index, last: index }
+        end
+      end
+    end
+
+    def blank?(value)
+      value.to_s.empty?
+    end
+  end
+end