labimotion 2.4.0.rc4 → 2.4.0.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1babeffe4e43eb088d5ab781101aa48574f67aab9abf0d32df4d883742e63788
-  data.tar.gz: 8c063d368a6af316e5397804951da314d8fc65035a852f56b066097091b0b2b3
+  metadata.gz: fa32d7e24804c4f270efdbce75bccf847ae3d30ae1f6b265c17b9c196e9c12a6
+  data.tar.gz: b6901471f70ac6874bf68a517ea9d994a3e4054d089a2bc66e042de38e97f4fd
 SHA512:
-  metadata.gz: 5d92879758e133fbf40fd433882967c8731ebf18e1e2586d8026a65b2d085359a530333cd740d00b7b0359981f155c034eee5687ffe326bb842c2dbc1ee52ad8
-  data.tar.gz: 3db447e733afbe176b1d7adb80078ef85899b473336e882d41bb9f7da4b66b51ca91d1f4084d30a0f644401e95c4312669bd1f9a6d7bc861af42dc8ad89d1abd
+  metadata.gz: b6612883678081acfa046ea9956424f06b512f5ea941cac2dd219e60809f0ed308026d9e0e8c9a112e067b8718f4a2b55939211b0843100d6329a9502341ddee
+  data.tar.gz: c52a79f87e8dffb30d340be92e107e6518c96e3c28d46a6857e6355ff3e30ec399a989cce94553188b4baff83ac548d34d80083b185a523be8c31823bdc7e97c

data/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 * Features and enhancements:
+  * `Link Element` is now available as a column type inside `Table` fields of generic elements and segments ([chem-generic-ui#1055](https://github.com/LabIMotion/chem-generic-ui/issues/1055), labimotion#261). A `drag_element` cell stores the same payload the layer-level field stores (`el_id`, `el_klass`, `el_label`, `el_name`, `el_tip`, `icon_name`) and deliberately carries no `is_new`/`cr_opt`: a drop links a record that already exists and must never create one on save, unlike the sample column it sits next to. The stored label, name, tooltip and icon are refreshed on every read by the new `Labimotion::Serializer.set_table_element`, called from `PropertiesEntity` and `ElnElementEntity` as well, so all three property loaders agree rather than drifting into three copies. `SampleAssociation.build_table_element` writes the `Labimotion::ElementsElement` join rows and feeds the same `els` list that the stale-link cleanup compares against — feeding it is load-bearing, since the cleanup would otherwise `destroy_all` the rows it had just created. Both paths skip a cell whose `el_klass` is a `Labimotion::LinkedElement::MODELS` key: such a column accepts reactions, wellplates, screens and the rest as readily as generic elements, and for those `el_id` is not a `Labimotion::Element` id, so resolving it would relabel or link a wholly unrelated element — the same guard the layer-level field already applies. Carried through every export path: XLSX (`exporter_helpers`, expandable like the sample and molecule columns, short label as the cell text and `Name` as an optional sub-column), DOCX (`export_element`), and the ZIP round-trip (`export_utils` remaps element ids to uuids, `import_utils` re-links them through the new `proc_table_element`). A linked element has no structure image, so the cell shows the klass icon instead of an SVG.
+  * Element cover images, write path ([chem-generic-ui#1050](https://github.com/LabIMotion/chem-generic-ui/issues/1050), labimotion#259): the element create and update saves now validate the `cover_images` key of the optional `metadata` param — an array of at most 3 `{ source: attachment|analysis, id: <integer> }` references, mirroring the chem-generic-ui picker's cap and vocabulary, normalized to exactly those two entry keys — and refuse a malformed selection with a plain 422 before any container/sample-association write runs. All cover-image helpers live in the dedicated `Labimotion::CoverImageHelpers` module, with the contract cap and source vocabulary as `Constants::CoverImage::MAX`/`SOURCES`. The rest of the metadata document keeps its existing contract: a present param replaces the stored hash wholesale, because its other writers (layer groups/restrictions from the details page, host regComps through the registry seam) remove a key by omitting it, while an absent param leaves stored metadata untouched — an old client that does not send `metadata` can never wipe a saved cover selection. References only, no FK: a deleted attachment/analysis leaves a dangling reference the UI skips at render time. No migration (`elements.metadata` and `elements_revisions.metadata` already exist), no entity change (`metadata` was already exposed), no klass change (the per-klass `cover_image` toggle rides the existing `update_settings` shallow merge); revision snapshots already carry `metadata` alongside `properties`, and restoring a revision round-trips the cover selection through this validated save.
+  * Element cover images, original serving ([chem-generic-ui#1050](https://github.com/LabIMotion/chem-generic-ui/issues/1050), labimotion#259): new `GET /generic_elements/cover_image?element_id=&source=&id=` answers the original file behind a cover-image reference, so the element page's display area can show originals while thumbnails stay in the picker. Gated by the `genericElement` matrix check plus `ElementPolicy` `read?` **and** `read_dataset?` (analysis previews are dataset attachments, and the ELN's own attachment reads demand both); the reference resolves through the element's own associations only, so a foreign attachment or container id answers 404, never a file. An `analysis` reference resolves the container preview server-side for the first time, mirroring the client's `getContainerImageData`: the container's `preferred_thumbnail` while it still exists, else the newest "combined" image, else the newest thumbnail-bearing dataset attachment. The body is the original bytes under the file's own content type — or the PNG thumbnail when a browser could not render the original (TIFF, raw-data files behind an analysis preview). An optional `variant=thumbnail` always answers the PNG thumbnail through the same gate and resolution, which is what the picker's rows show — for an svg the stored thumbnail (black: ImageMagick reads `transparent` as black) is replaced by a fresh white-background rasterization of the original, through the same shared converter as the docx export — with it, the whole cover-image feature runs on gem-owned API surface and the host wires no fetcher at all. The picker's Save persists directly through the new `POST /generic_elements/cover_images` (`element_id`, `cover_images`; gated by `ElementPolicy` `update?` + the matrix check): the same validation as the element-save path, then a **targeted merge** of exactly the `cover_images` key into the stored metadata — deliberately narrower than the element save's wholesale-replace contract, so this writer can neither wipe nor resurrect `groups`/host keys. Live like klass settings: the write is immediate and unversioned until the next element save snapshots metadata into the revisions. The docx export (`ExportElement`) now renders the cover selection too: the stored references resolve through the same helpers as the `cover_image` endpoint, each image is embedded above the layers (originals for the rasters Word renders reliably — png/jpeg/gif/bmp; other renderable originals such as svg are rasterized onto white via MiniMagick, with the CSS keyword `transparent` normalized to `none` first because ImageMagick’s own SVG renderer reads it as black — the PNG thumbnail only as last resort), captioned "ref: …" and scaled to the page via MiniMagick-read dimensions (best effort — without them the template placeholder geometry is kept), Requires the matching `Labimotion_lines.docx` template change in the host ELN (a `has_cover`-guarded `cover_images:each` block before the layers loop); an old template simply ignores the new context keys.
   * Share notifications now fire from the gem itself ([chem-generic-ui#1040](https://github.com/LabIMotion/chem-generic-ui/issues/1040), labimotion#255): a successful grant or level change (`POST /generic_klass/shares`), an ownership transfer (`POST /generic_klass/transfer_ownership`) and the ask that creates an access-request row (`POST /generic_klass/request_access`, `created: true` only — repeat asks are not repeat pings) each send the toast the host's `Chemotion::TemplateShareAPI` used to send, through the new `Labimotion::ShareNotifier`. Recipients are Persons only, never the actor; the channel is looked up by the literal subject `'Template Share Notification'` (the host ELN's channel migration stays required for delivery); and the notifier rescues internally — an undeliverable notification is a notification not sent, never a failed share. A host without Message/Channel machinery (or without the channel row) silently sends nothing. The level-change route (`PUT /shares/:id`) stays silent, matching the host layer it replaces. Until the matching ELN change removes `TemplateShareAPI` and its caller, grants on the integration branches notify twice — accepted, dev-only.
   * Per-template ownership and sharing, backend ([chem-generic-ui#1001](https://github.com/LabIMotion/chem-generic-ui/issues/1001) Phase 2): `klass_shares` table (viewer/editor/owner, one owner per template enforced by a partial unique index), `authorize_klass!` per-template gate replacing the designer-wide check on template mutation endpoints (owner-less templates keep the legacy behaviour permanently), share management endpoints under `/generic_klass/shares` plus `/generic_klass/transfer_ownership`, and capability booleans (`can_write` … `can_manage`) on the Designer list payloads. `download_klass` is now gated (`:read`) and no longer writes an identifier during a GET. Requires host ELN twin migrations `create_klass_shares` and `seed_klass_share_owners` (the latter seeds owner rows from `created_by` in raw SQL, idempotent via `ON CONFLICT DO NOTHING`); deploy order is migrate → **restart** (the stale schema cache otherwise silently drops the running app's writes to the new table). Ships as one upgrade with the matching chem-generic-ui and ELN changes — see the design doc's ADR 0001.
   * `created_by` and `created_at` are now `NOT NULL` on `element_klasses` and `segment_klasses` ([chem-generic-ui#1018](https://github.com/LabIMotion/chem-generic-ui/issues/1018)); `dataset_klasses` already declared both. Two new migrations, back-dated ahead of `create_klass_shares`: `backfill_klass_created_columns` fills a NULL `created_by` with the first system administrator (falling back to the lowest-id user of any type, and raising if the `users` table is empty) and a NULL `created_at` with `COALESCE(updated_at, NOW())`; `tighten_klass_created_columns` then applies the constraints — data before constraint. The back-dating is what lets `seed_klass_share_owners` stay unchanged: with `created_by` already filled in, its `WHERE created_by IS NOT NULL` filter excludes nothing and every template gets an owner row instead of staying owner-less on the permanent legacy gate. The backfill re-runs that owner seed itself (`ON CONFLICT DO NOTHING`) so a database on which the seed had already run picks up the repaired rows. Requires host ELN twin migrations for both, back-dated the same way; deploy order is migrate → **restart** (the stale schema cache otherwise silently drops the running app's writes).

data/lib/labimotion/apis/generic_element_api.rb

@@ -16,6 +16,7 @@ module Labimotion
     helpers Labimotion::VocabularyHelpers
     helpers Labimotion::GenericHelpers
     helpers Labimotion::ElementHelpers
+    helpers Labimotion::CoverImageHelpers
     helpers Labimotion::ParamHelpers
 
     resource :generic_elements do
@@ -108,6 +109,31 @@ module Labimotion
           Labimotion.log_exception(e, current_user)
           { attributes: [], error: e.message }
         end
+
+        desc 'List the selectable inline attributes of a klass, with no element instance'
+        params do
+          requires :el_klass, type: String, desc: 'Generic klass name or permit-target key (reaction, sample, ...)'
+        end
+        get 'for_klass' do
+          error!('401 Unauthorized', 401) unless current_user
+
+          # Template shape only — no instance is read, so there is nothing
+          # collection-scoped to authorize beyond being a signed-in user.
+          { attributes: Labimotion::LinkedElement.available_for_klass(params[:el_klass]) }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { attributes: [], error: e.message }
+        end
+
+        desc 'List the standard ELN element types a drag field can link'
+        get 'permit_targets' do
+          error!('401 Unauthorized', 401) unless current_user
+
+          { permit_targets: Labimotion::LinkedElement.permit_targets }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { permit_targets: [], error: e.message }
+        end
       end
 
       namespace :search_basic_by_like do
@@ -530,6 +556,58 @@ module Labimotion
         { generic_elements: [] }
       end
 
+      # Declared before `route_param :id` so the literal segment is not
+      # swallowed by the id capture.
+      namespace :cover_images do
+        desc 'Save the cover-image selection directly (live, like klass settings)'
+        params do
+          requires :element_id, type: Integer, desc: 'Element id'
+          requires :cover_images, type: Array, desc: 'Ordered {source, id} references; [] clears'
+        end
+        post do
+          element = Labimotion::Element.find(params[:element_id])
+          unless current_user.matrix_check_by_name('genericElement') &&
+                 ElementPolicy.new(current_user, element).update?
+            error!('401 Unauthorized', 401)
+          end
+
+          { mc: 'ss00', cover_images: save_cover_images(element, params[:cover_images]) }
+        rescue ActiveRecord::RecordNotFound
+          error!('404 Not Found', 404)
+        end
+      end
+
+      namespace :cover_image do
+        desc 'Serve the image behind a cover-image reference (original or thumbnail)'
+        params do
+          requires :element_id, type: Integer, desc: 'Element id'
+          requires :source, type: String, values: Labimotion::Constants::CoverImage::SOURCES,
+                            desc: 'Reference source'
+          requires :id, type: Integer, desc: 'Attachment or analysis-container id'
+          optional :variant, type: String, values: %w[original thumbnail], default: 'original',
+                             desc: 'original file (display area) or PNG thumbnail (picker rows)'
+        end
+        get do
+          element = Labimotion::Element.find(params[:element_id])
+          policy = ElementPolicy.new(current_user, element)
+          unless current_user.matrix_check_by_name('genericElement') && policy.read? && policy.read_dataset?
+            error!('401 Unauthorized', 401)
+          end
+
+          attachment = cover_image_attachment(element, params[:source], params[:id])
+          payload = attachment && cover_image_body(attachment, params[:variant])
+          error!('404 Not Found', 404) if payload.nil?
+
+          data, mime_type = payload
+          env['api.format'] = :binary
+          content_type(mime_type || 'application/octet-stream')
+          header('Content-Disposition', "inline; filename=\"#{CGI.escape(attachment.filename.to_s)}\"")
+          data
+        rescue ActiveRecord::RecordNotFound
+          error!('404 Not Found', 404)
+        end
+      end
+
       desc 'Return serialized element by id'
       params do
         requires :id, type: Integer, desc: 'Element id'
@@ -547,6 +625,7 @@ module Labimotion
           {
             element: Labimotion::ElementEntity.represent(
               element,
+              current_user: current_user,
               detail_levels: ElementDetailLevelCalculator.new(user: current_user, element: element).detail_levels,
               policy: @element_policy
             ),
@@ -591,6 +670,7 @@ module Labimotion
             {
               element: Labimotion::ElementEntity.represent(
                 element,
+                current_user: current_user,
                 detail_levels: ElementDetailLevelCalculator.new(user: current_user, element: element).detail_levels,
               ),
               attachments: Entities::AttachmentEntity.represent(element&.attachments),

data/lib/labimotion/apis/user_klass_settings_api.rb

@@ -3,7 +3,8 @@
 require 'labimotion/version'
 
 module Labimotion
-  # Per-user, per-klass UI settings API (toolbar Overview/Arrange visibility).
+  # Per-user, per-klass UI settings API (toolbar Overview/Arrange visibility, and
+  # the default inline attributes of a linked element).
   # Every route is scoped to the authenticated user via created_by, so a user
   # only ever reads/writes their own setting; no klass-edit permission needed.
   class UserKlassSettingsAPI < Grape::API
@@ -14,15 +15,37 @@ module Labimotion
         Labimotion::UserKlassSetting.where(created_by: current_user.id)
       end
 
-      def klass_toolbar(settings)
-        (settings || {})['toolbar'] || (settings || {})[:toolbar] || {}
+      # Only the sub-settings actually present in the request are written, so a
+      # save carrying just one of them leaves the other untouched. Absent reads
+      # as "leave alone"; an empty linked_el_attrs array reads as "clear".
+      def submitted_settings(settings)
+        settings = (settings || {}).transform_keys(&:to_s)
+        toolbar = settings[Labimotion::Constants::UserSetting::TOOLBAR]
+        attrs = settings[Labimotion::Constants::UserSetting::LINKED_EL_ATTRS]
+        {}.tap do |result|
+          result[Labimotion::Constants::UserSetting::TOOLBAR] = toolbar if toolbar.is_a?(Hash)
+          if attrs.is_a?(Array)
+            result[Labimotion::Constants::UserSetting::LINKED_EL_ATTRS] = normalize_linked_el_attrs(attrs)
+          end
+        end
+      end
+
+      # Persist only the identity of each attribute. The values are resolved live
+      # on every load, and the label is refreshed from the template alongside them.
+      def normalize_linked_el_attrs(attrs)
+        attrs.filter_map do |attr|
+          attr = attr.transform_keys(&:to_s) if attr.respond_to?(:transform_keys)
+          next unless attr.is_a?(Hash) && attr['key'].present?
+
+          { 'source' => attr['source'], 'key' => attr['key'], 'label' => attr['label'] }
+        end
       end
     end
 
     resource :user_klass_settings do
       desc 'Fetch the current user UI setting for a klass'
       params do
-        requires :klass, type: String, values: %w[ElementKlass SegmentKlass DatasetKlass], desc: 'Klass type'
+        requires :klass, type: String, values: Labimotion::Constants::Klass::USER_SETTINGS, desc: 'Klass type'
         requires :identifier, type: String, desc: 'Klass identifier'
       end
       get 'fetch' do
@@ -48,7 +71,7 @@ module Labimotion
         )
         record.klass_label = params[:klass_label] if params[:klass_label]
         record.created_by ||= current_user.id
-        record.settings = (record.settings || {}).merge('toolbar' => klass_toolbar(params[:settings]))
+        record.settings = (record.settings || {}).merge(submitted_settings(params[:settings]))
         record.save!
         { mc: 'ss00', data: Labimotion::UserKlassSettingEntity.represent(record) }
       rescue StandardError => e

data/lib/labimotion/constants.rb

@@ -17,6 +17,14 @@ module Labimotion
       CV = 'Cyclic Voltammetry'
     end
 
+    # The element cover selection (labimotion#259): cap and source vocabulary
+    # of `metadata.cover_images` entries. Mirrored by the chem-generic-ui
+    # cover-image picker (chem-generic-ui#1050) — keep them in sync.
+    module CoverImage
+      SOURCES = %w[attachment analysis].freeze
+      MAX = 3
+    end
+
     module Mapper
       NMR_CONFIG = ::File.join(__dir__, 'libs', 'data', 'mapper', 'Source.json').freeze
       WIKI_CONFIG = ::File.join(__dir__, 'libs', 'data', 'mapper', 'Chemwiki.json').freeze
@@ -27,6 +35,20 @@ module Labimotion
       SEGMENT = 'SegmentKlass'
       DATASET = 'DatasetKlass'
       ALL = [ELEMENT, SEGMENT, DATASET].freeze
+
+      # Standard ELN elements (sample, reaction, molecule, ...) have no klass
+      # model. Per-user settings that key on one use this pseudo-type, with the
+      # permit-target key itself as the klass identifier — see
+      # Labimotion::UserKlassSetting.
+      PERMIT_TARGET = 'PermitTarget'
+      USER_SETTINGS = [ELEMENT, SEGMENT, DATASET, PERMIT_TARGET].freeze
+    end
+
+    # The independent sub-settings held side by side in
+    # user_klass_settings.settings. A save writes only the ones it carries.
+    module UserSetting
+      TOOLBAR = 'toolbar'
+      LINKED_EL_ATTRS = 'linked_el_attrs'
     end
 
     # The designer-right families as keyed in `users.generic_admin` (host-owned jsonb) and

data/lib/labimotion/entities/eln_element_entity.rb

@@ -68,6 +68,12 @@ module Labimotion
             object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
               set_table(field, field_table_samples, Labimotion::Prop::SAMPLE)
           end
+
+          field_table_elements = field[Labimotion::Prop::SUBFIELDS].select { |ss| ss['type'] == Labimotion::FieldType::DRAG_ELEMENT }
+          if field_table_elements.present?
+            object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
+              Labimotion::Serializer.set_table_element(field, field_table_elements)
+          end
         end
       end
       object.properties

data/lib/labimotion/entities/properties_entity.rb

@@ -97,15 +97,55 @@ module Labimotion
       return unless field['value'].is_a?(Hash)
 
       attrs = field.dig('value', 'el_attrs')
+      el_klass = field.dig('value', 'el_klass')
+      el_id = field.dig('value', 'el_id')
+      el_type = field.dig('value', 'el_type')
+      linked = Labimotion::LinkedElement.new(el_klass, el_id, el_type)
+
+      # A missing el_attrs means the user never picked anything for this link, so
+      # their My LabIMotion default applies. An explicit [] means they picked none
+      # — the two must not collapse, or clearing a selection would not stick.
+      from_default = attrs.nil?
+      attrs = default_linked_attrs(el_klass, el_type) if from_default
       return unless attrs.is_a?(Array) && attrs.present?
       return unless object.properties.dig(Labimotion::Prop::LAYERS, key, Labimotion::Prop::FIELDS, idx,
                                           'value').present?
 
-      el_klass = field.dig('value', 'el_klass')
-      el_id = field.dig('value', 'el_id')
-      el_type = field.dig('value', 'el_type')
-      object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx]['value']['el_attrs'] =
-        Labimotion::LinkedElement.new(el_klass, el_id, el_type).resolve(attrs)
+      resolved = linked.resolve(attrs)
+      resolved = resolved.map { |attr| mark_default(attr) } if from_default
+      object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx]['value']['el_attrs'] = resolved
+    end
+
+    def mark_default(attr)
+      attr.is_a?(Hash) ? attr.merge(Labimotion::LinkedElement::IS_DEFAULT => true) : attr
+    end
+
+    # Keyed by what the drag field itself stores — el_klass for a generic element
+    # or a standard type, el_type for drag_molecule, which omits el_klass. Read
+    # straight off the preloaded map rather than via LinkedElement#target_key, so
+    # a field with no default costs no query.
+    def default_linked_attrs(el_klass, el_type)
+      map = default_linked_attrs_map
+      return [] if map.empty?
+
+      map[el_klass.to_s] || map[el_type.to_s] || []
+    end
+
+    # The current user's defaults for every linked target, loaded once per
+    # represented object. Skipped when no user is in scope (this entity is also
+    # rendered from contexts that pass none, e.g. Hub submissions and exports) and
+    # for list views, which don't render the inline attributes and would otherwise
+    # pay the lookup once per row.
+    def default_linked_attrs_map
+      return @default_linked_attrs_map if defined?(@default_linked_attrs_map)
+
+      user_id = options[:current_user]&.id
+      @default_linked_attrs_map =
+        if user_id.blank? || displayed_in_list?
+          {}
+        else
+          Labimotion::UserKlassSetting.linked_el_attrs_by_el_klass(user_id)
+        end
     end
 
     def update_reaction_field(key, field, idx)
@@ -144,10 +184,18 @@ module Labimotion
       field_table_samples = field[Labimotion::Prop::SUBFIELDS].select do |ss|
         ss['type'] == Labimotion::FieldType::DRAG_SAMPLE
       end
-      return unless field_table_samples.present?
+      if field_table_samples.present?
+        object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
+          set_table(field, field_table_samples, Labimotion::Prop::SAMPLE)
+      end
+
+      field_table_elements = field[Labimotion::Prop::SUBFIELDS].select do |ss|
+        ss['type'] == Labimotion::FieldType::DRAG_ELEMENT
+      end
+      return unless field_table_elements.present?
 
       object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] =
-        set_table(field, field_table_samples, Labimotion::Prop::SAMPLE)
+        Labimotion::Serializer.set_table_element(field, field_table_elements)
     end
 
     def update_voc_field(key, field, idx)

data/lib/labimotion/helpers/cover_image_helpers.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'grape'
+require 'labimotion/constants'
+
+module Labimotion
+  ## Element cover images (chem-generic-ui#1050, labimotion#259).
+  ## `cover_images` is the one element-metadata key whose shape the gem owns:
+  ## validation and normalization of the stored references, their direct
+  ## save, the resolution of a reference to the attachment holding its
+  ## picture, and the bytes served for the display area (originals), the
+  ## picker rows (thumbnails) and the docx export.
+  module CoverImageHelpers
+    extend Grape::API::Helpers
+
+    # Element metadata is a client-round-tripped document with several writers —
+    # layer groups/restrictions from the element details page, host regComps
+    # through the registry seam — and those writers remove a key by omitting it.
+    # So a present :metadata param replaces the stored hash wholesale; only an
+    # absent param leaves the stored metadata untouched (an old client that does
+    # not send :metadata must never wipe a saved cover selection). `cover_images`
+    # is the one key the gem owns: its entries are validated against the picker's
+    # cap and source vocabulary and normalized to exactly source/id, so nothing
+    # else reaches the jsonb column through that key.
+    def prepare_element_metadata(stored, incoming)
+      return stored || {} if incoming.nil?
+
+      # to_h returns self for a plain Hash — dup so the caller's copy stays intact.
+      metadata = incoming.to_h.dup
+      return metadata unless metadata.key?('cover_images') || metadata.key?(:cover_images)
+
+      entries = metadata.key?('cover_images') ? metadata['cover_images'] : metadata[:cover_images]
+      metadata.delete(:cover_images)
+      metadata['cover_images'] = validate_cover_images!(entries)
+      metadata
+    end
+
+    def validate_cover_images!(entries)
+      cover_images_error!('must be an array') unless entries.is_a?(Array)
+      max = Constants::CoverImage::MAX
+      cover_images_error!("holds at most #{max} entries") if entries.size > max
+
+      entries.map { |entry| normalized_cover_image!(entry) }
+    end
+
+    def normalized_cover_image!(entry)
+      cover_image_entry_error! unless entry.is_a?(Hash)
+      source = entry['source'] || entry[:source]
+      id = entry['id'] || entry[:id]
+      cover_image_entry_error! unless Constants::CoverImage::SOURCES.include?(source) && id.is_a?(Integer)
+      { 'source' => source, 'id' => id }
+    end
+
+    def cover_image_entry_error!
+      cover_images_error!("entries must be { source: #{Constants::CoverImage::SOURCES.join(' | ')}, id: integer }")
+    end
+
+    def cover_images_error!(reason)
+      error!("metadata.cover_images #{reason}", 422)
+    end
+
+    # Direct write of the one gem-owned metadata key (the cover picker's
+    # Save): a targeted merge, deliberately narrower than the element save's
+    # wholesale-replace contract — this writer owns exactly cover_images and
+    # can neither wipe nor resurrect any other key. Live like klass settings:
+    # not versioned until the next element save snapshots metadata.
+    def save_cover_images(element, entries)
+      validated = validate_cover_images!(entries)
+      element.update!(metadata: (element.metadata || {}).merge('cover_images' => validated))
+      validated
+    end
+
+    # Resolves a stored cover-image reference to the Attachment holding its
+    # picture, or nil. Ownership is part of the resolution: an attachment is
+    # looked up through the element's own association, an analysis must be one
+    # of the element's analyses — a foreign id answers nil, never a file.
+    def cover_image_attachment(element, source, sid)
+      case source
+      when 'attachment'
+        element.attachments.find_by(id: sid)
+      when 'analysis'
+        container = element.analyses.find_by(id: sid)
+        container && analysis_preview_attachment(container)
+      end
+    end
+
+    # Server twin of the ELN client's getContainerImageData: among the
+    # thumbnail-bearing attachments of the analysis' dataset children, the
+    # container's preferred_thumbnail wins while it still exists, then the
+    # newest "combined" image, then the newest overall.
+    def analysis_preview_attachment(container)
+      dataset_ids = container.children.where(container_type: 'dataset').pluck(:id)
+      return nil if dataset_ids.empty?
+
+      candidates = Attachment.where(attachable_type: 'Container', attachable_id: dataset_ids, thumb: true).to_a
+      pick_preview_attachment(container, candidates)
+    end
+
+    def pick_preview_attachment(container, candidates)
+      return nil if candidates.empty?
+
+      preferred = preferred_candidate(container, candidates)
+      return preferred if preferred
+
+      combined = candidates.select { |att| att.filename.to_s.downcase.include?('combined') }
+      (combined.empty? ? candidates : combined).max_by(&:updated_at)
+    end
+
+    # hstore values are strings — the stored preferred_thumbnail id arrives as '1'.
+    def preferred_candidate(container, candidates)
+      preferred_id = (container.extended_metadata || {})['preferred_thumbnail'].to_i
+      candidates.find { |att| att.id == preferred_id }
+    end
+
+    # The picker's rows ask for variant=thumbnail — the small uniform PNG;
+    # everything else means the original (display area). An svg's STORED
+    # thumbnail is black (see cover_rasterize), so it is re-rasterized from
+    # the original instead, falling back to the stored one.
+    def cover_image_body(att, variant)
+      return cover_image_payload(att) unless variant == 'thumbnail'
+
+      thumb = svg_cover_thumbnail(att) || att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    end
+
+    COVER_THUMB_RESIZE = '256x256>'
+
+    def svg_cover_thumbnail(att)
+      mime = att.content_type.to_s.downcase
+      return nil unless mime.include?('svg')
+
+      data = att.read_file
+      data && cover_rasterize(data, mime, resize: COVER_THUMB_RESIZE)
+    end
+
+    ## ImageMagick's own SVG renderer reads the CSS keyword `transparent` as
+    ## black — the defect behind the ELN thumbnails' black background — so
+    ## paint properties are normalized to `none` first and the result is a
+    ## PNG flattened onto white. Nil when conversion is unavailable or
+    ## fails; callers fall back.
+    SVG_TRANSPARENT_RE =
+      /((?:fill|stroke|stop-color|flood-color|background(?:-color)?)\s*[:=]\s*["']?)transparent\b/i
+
+    def cover_rasterize(data, mime, resize: nil)
+      # Deferred on purpose: mini_magick is a host-bundle gem, not a
+      # dependency of this gem — at the top of the file it would break gem
+      # load (and the spec suite) on a host without it, while here a miss is
+      # rescued below into the nil fallback.
+      require 'mini_magick'
+      data = data.gsub(SVG_TRANSPARENT_RE, '\1none') if mime.include?('svg')
+      image = MiniMagick::Image.read(data, cover_read_ext(mime))
+      image.format('png') do |convert|
+        convert.background('white')
+        convert.flatten
+        convert.resize(resize) if resize
+      end
+      image.to_blob
+    rescue LoadError, StandardError => e
+      Labimotion.log_exception(e)
+      nil
+    end
+
+    def cover_read_ext(mime)
+      subtype = mime.split('/').last.to_s.sub('+xml', '')
+      subtype.empty? ? '.img' : ".#{subtype}"
+    end
+
+    # The bytes + content type to serve for a cover attachment: the original
+    # file whenever a browser can render it, otherwise the PNG thumbnail
+    # (TIFF originals, raw-data files behind an analysis preview). Nil when
+    # neither is readable.
+    def cover_image_payload(att)
+      if att.type_image? && !att.type_image_tiff?
+        data = att.read_file
+        return [data, att.content_type] if data
+      end
+      thumb = att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    end
+  end
+end

data/lib/labimotion/helpers/element_helpers.rb

@@ -3,11 +3,16 @@
 require 'grape'
 require 'labimotion/conf'
 require 'labimotion/utils/utils'
+require 'labimotion/helpers/cover_image_helpers'
 # require 'labimotion/models/element_klass'
 module Labimotion
   ## ElementHelpers
   module ElementHelpers
     extend Grape::API::Helpers
+    # the element save validates metadata.cover_images up front through
+    # prepare_element_metadata — carry the dependency instead of relying on
+    # both modules being mounted on the same Grape endpoint
+    include Labimotion::CoverImageHelpers
 
     def klass_list(is_generic_only)
       if is_generic_only == true
@@ -267,7 +272,7 @@ module Labimotion
         klass_uuid: klass[:uuid],
         properties: properties,
         properties_release: params[:properties_release],
-        metadata: params[:metadata] || {},
+        metadata: prepare_element_metadata({}, params[:metadata]),
         created_by: current_user.id
       }
       element = Labimotion::Element.new(attributes)
@@ -295,6 +300,11 @@ module Labimotion
 
     def update_element_by_id(current_user, params)
       element = Labimotion::Element.find(params[:id])
+      # Validated up front, before the container/sample-association writes run:
+      # a rejected cover selection must fail the request whole, not leave a
+      # half-applied datamodel behind. error! throws rather than raises, so it
+      # escapes this method's rescue-and-log and reaches the client as a 422.
+      metadata = prepare_element_metadata(element.metadata, params[:metadata])
       update_datamodel(params[:container], current_user)
       properties = update_sample_association(params[:properties], current_user, element)
       params.delete(:container)
@@ -303,7 +313,6 @@ module Labimotion
       params.delete(:user_labels)
       attributes = declared(params.except(:segments), include_missing: false)
       properties['pkg'] = Labimotion::Utils.pkg(properties['pkg'])
-      metadata = params[:metadata] || element.metadata || {}
       if element.klass_uuid != properties['klass_uuid'] || element.properties != properties || element.name != params[:name] || element.metadata != metadata
         properties['klass'] = 'Element'
         uuid = SecureRandom.uuid

data/lib/labimotion/helpers/exporter_helpers.rb

@@ -13,9 +13,13 @@ module Labimotion
       col_name
     end
 
-    # Check if field type should be expanded (DRAG_SAMPLE or DRAG_MOLECULE)
+    # Check if field type should be expanded (DRAG_SAMPLE, DRAG_MOLECULE or DRAG_ELEMENT)
     def expandable_field?(field_type)
-      [Labimotion::FieldType::DRAG_SAMPLE, Labimotion::FieldType::DRAG_MOLECULE].include?(field_type)
+      [
+        Labimotion::FieldType::DRAG_SAMPLE,
+        Labimotion::FieldType::DRAG_MOLECULE,
+        Labimotion::FieldType::DRAG_ELEMENT
+      ].include?(field_type)
     end
 
     # Generate sanitized filename for export
@@ -34,6 +38,8 @@ module Labimotion
       case sub_field['type']
       when Labimotion::FieldType::DRAG_SAMPLE, Labimotion::FieldType::DRAG_MOLECULE
         format_drag_field_cell(sub_val, sub_field)
+      when Labimotion::FieldType::DRAG_ELEMENT
+        format_element_cell(sub_val, sub_field)
       when Labimotion::FieldType::SELECT
         format_select_cell(sub_val, sub_field)
       when Labimotion::FieldType::SYSTEM_DEFINED
@@ -95,6 +101,15 @@ module Labimotion
       end
     end
 
+    # Format drag_element cell — a linked element has no structure image,
+    # so the short label is the cell text
+    def format_element_cell(sub_val, sub_field)
+      val = sub_val[sub_field['id']]['value'] || {}
+      return '' if val.blank?
+
+      val['el_label'].present? ? val['el_label'].to_s : val['el_name'].to_s
+    end
+
     # Format select cell
     def format_select_cell(sub_val, sub_field)
       sub_val[sub_field['id']]['value'].to_s

data/lib/labimotion/helpers/param_helpers.rb

@@ -225,7 +225,7 @@ module Labimotion
     end
 
     params :user_klass_settings_save do
-      requires :klass, type: String, values: %w[ElementKlass SegmentKlass DatasetKlass], desc: 'Klass type'
+      requires :klass, type: String, values: Labimotion::Constants::Klass::USER_SETTINGS, desc: 'Klass type'
       requires :klass_identifier, type: String, desc: 'Stable klass identifier'
       optional :klass_label, type: String, desc: 'Klass label (display only)'
       requires :settings, type: Hash do
@@ -233,6 +233,14 @@ module Labimotion
           optional :overview, type: Boolean, default: true
           optional :arrange, type: Boolean, default: true
         end
+        # The user's default inline attributes for elements linked from a
+        # drag field. Only the identity of each attribute is stored; the values
+        # are resolved live on every load. An empty array clears the default.
+        optional :linked_el_attrs, type: Array do
+          requires :key, type: String, desc: 'Attribute key (layer::field, or column name)'
+          optional :source, type: String, desc: 'property or column'
+          optional :label, type: String, desc: 'Attribute label (display only)'
+        end
       end
     end
   end

data/lib/labimotion/helpers/sample_association_helpers.rb

@@ -19,6 +19,13 @@ module Labimotion
       []
     end
 
+    def build_table_element(field_tables, current_user, element)
+      Labimotion::SampleAssociation.build_table_element(field_tables, current_user, element)
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      []
+    end
+
     def update_sample_association(properties, current_user, element)
       Labimotion::SampleAssociation.update_sample_association(properties, current_user, element)
     rescue StandardError => e

data/lib/labimotion/libs/export_element.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 require 'date'
 require 'ostruct'
+require 'tempfile'
 require 'export_table'
 require 'labimotion/version'
 require 'labimotion/utils/units'
+require 'labimotion/helpers/cover_image_helpers'
 require 'sablon'
 
 module Labimotion
@@ -33,6 +35,7 @@ module Labimotion
       @properties = element.properties
       @options = element.properties_release[Labimotion::Prop::SEL_OPTIONS]
       @export_format = export_format
+      @cover_tempfiles = []
     rescue StandardError => e
       Labimotion.log_exception(e)
     end
@@ -396,6 +399,7 @@ module Labimotion
     TABLE_CELL_TEXT_RENDERERS = {
       Labimotion::FieldType::DRAG_SAMPLE => ->(_sf, c, ctx) { ctx.table_cell_sample_text(c['value'] || {}) },
       Labimotion::FieldType::DRAG_MOLECULE => ->(_sf, c, ctx) { ctx.table_cell_molecule_text(c['value'] || {}) },
+      Labimotion::FieldType::DRAG_ELEMENT => ->(_sf, c, ctx) { ctx.table_cell_element_text(c['value'] || {}) },
       Labimotion::FieldType::SELECT => ->(_sf, c, _ctx) { c['value'].to_s },
       Labimotion::FieldType::SYSTEM_DEFINED => ->(sf, c, ctx) { ctx.table_cell_sysdef_text(sf, c) }
     }.freeze
@@ -430,6 +434,13 @@ module Labimotion
       parts.join("\n")
     end
 
+    def table_cell_element_text(val)
+      parts = []
+      parts << "Short Label: [#{val['el_label']}]" if val['el_label'].present?
+      parts << "Name: [#{val['el_name']}]" if val['el_name'].present?
+      parts.join("\n")
+    end
+
     def table_cell_sysdef_text(sub_field, cell)
       fdef = Labimotion::Units::FIELDS.find { |o| o[:field] == sub_field['option_layers'] }
       unit = fdef&.fetch(:units, [])&.find { |u| u[:key] == cell['value_system'] }&.fetch(:label, '')
@@ -454,10 +465,21 @@ module Labimotion
       # location = Rails.root.join('lib', 'template', 'Labimotion.docx')
       location = Rails.root.join('lib', 'template', 'Labimotion_lines.docx')
       # location = Rails.root.join('lib', 'template', 'Labimotion_img.docx')
-      File.exist?(location)
       template = Sablon.template(location)
-      layers = build_layers
-      context = {
+      tempfile = Tempfile.new('labimotion.docx')
+      template.render_to_file File.expand_path(tempfile), docx_context
+      File.read(tempfile)
+    rescue StandardError => e
+      Labimotion.log_exception(e)
+    ensure
+      # Close and delete the temporary files
+      tempfile&.close
+      tempfile&.unlink
+      close_cover_tempfiles
+    end
+
+    def docx_context
+      {
         label: @element_klass.label,
         desc: @element_klass.desc,
         name: @name,
@@ -465,18 +487,111 @@ module Labimotion
         short_label: @short_label,
         date: Time.now.strftime('%d/%m/%Y'),
         author: @current_user.name,
-        layers: layers
-      }
-      tempfile = Tempfile.new('labimotion.docx')
-      template.render_to_file File.expand_path(tempfile), context
-      content = File.read(tempfile)
-      content
+        layers: build_layers
+      }.merge(cover_context)
+    end
+
+    def close_cover_tempfiles
+      Array(@cover_tempfiles).each(&:close!)
+    end
+
+    ## The element's cover selection (chem-generic-ui#1050) rendered into the
+    ## export: the stored `{source, id}` references are resolved through the
+    ## same helpers as the cover_image API, so the docx shows exactly what the
+    ## element page shows. Only rasters Word renders reliably are embedded as
+    ## originals; everything else falls back to the PNG thumbnail.
+    DOCX_COVER_MIMES = %w[image/png image/jpeg image/gif image/bmp].freeze
+    DOCX_COVER_EXT = {
+      'image/png' => '.png',
+      'image/jpeg' => '.jpg',
+      'image/gif' => '.gif',
+      'image/bmp' => '.bmp'
+    }.freeze
+    # px-unit bounds of the rendered image (Sablon::Image::PX_TO_EMU scale):
+    # 1600 ≈ 13.3cm wide, 1100 ≈ 9.2cm tall
+    DOCX_COVER_MAX_W = 1600
+    DOCX_COVER_MAX_H = 1100
+
+    def cover_context
+      covers = build_cover_images
+      { has_cover: covers.present?, cover_images: covers }
+    end
+
+    def build_cover_images
+      return [] unless @element.instance_of?(Labimotion::Element)
+
+      refs = @element.metadata&.fetch('cover_images', nil) || []
+      refs.filter_map { |ref| build_cover_image(ref) }
     rescue StandardError => e
       Labimotion.log_exception(e)
-    ensure
-      # Close and delete the temporary file
-      tempfile&.close
-      tempfile&.unlink
+      []
+    end
+
+    def build_cover_image(ref)
+      att = cover_helpers.cover_image_attachment(@element, ref['source'], ref['id'])
+      data, mime = att && docx_cover_payload(att)
+      return nil if data.nil?
+
+      { image: docx_cover_sablon_image(data, mime), caption: docx_cover_caption(ref, att) }
+    rescue StandardError => e
+      Labimotion.log_exception(e)
+      nil
+    end
+
+    def docx_cover_payload(att)
+      original = docx_cover_original(att)
+      return original if original
+
+      thumb = att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    end
+
+    def docx_cover_original(att)
+      return nil unless att.type_image? && !att.type_image_tiff?
+
+      mime = att.content_type.to_s.downcase
+      data = att.read_file
+      return nil if data.nil?
+      return [data, mime] if DOCX_COVER_MIMES.include?(mime)
+
+      # the template's blip placeholder takes bitmaps only, so svg & friends
+      # are rasterized onto white through the shared cover helper
+      converted = cover_helpers.cover_rasterize(data, mime)
+      [converted, 'image/png'] if converted
+    end
+
+    def docx_cover_sablon_image(data, mime)
+      tmp = Tempfile.new(['labimotion-cover', DOCX_COVER_EXT.fetch(mime, '.png')])
+      tmp.binmode
+      tmp.write(data)
+      tmp.flush
+      @cover_tempfiles << tmp
+      image = Sablon::Image.create_by_path(tmp.path)
+      apply_docx_cover_dimensions(image, data)
+      image
+    end
+
+    ## Without dimensions the placeholder geometry of the template is kept,
+    ## which distorts the aspect ratio — best effort, never fatal.
+    def apply_docx_cover_dimensions(image, data)
+      require 'mini_magick'
+      width, height = MiniMagick::Image.read(data).dimensions
+      return unless width.to_i.positive? && height.to_i.positive?
+
+      scale = [1.0, DOCX_COVER_MAX_W.to_f / width, DOCX_COVER_MAX_H.to_f / height].min
+      image.px_width = (width * scale).round
+      image.px_height = (height * scale).round
+    rescue LoadError, StandardError => e
+      Labimotion.log_exception(e)
+    end
+
+    def docx_cover_caption(ref, att)
+      label = ref['source'] == 'analysis' ? @element.analyses.find_by(id: ref['id'])&.name : att.filename
+      "ref: #{ref['source']}: #{label}"
+    end
+
+    def cover_helpers
+      @cover_helpers ||= Object.new.extend(Labimotion::CoverImageHelpers)
     end
 
 

data/lib/labimotion/libs/linked_element.rb

@@ -17,6 +17,11 @@ module Labimotion
     SOURCE_PROPERTY = 'property'
     SOURCE_COLUMN = 'column'
 
+    # Marks an attribute injected from the user's stored default rather than
+    # picked on this element. Stripped again before properties are persisted, so
+    # a default never silently becomes an explicit per-instance selection.
+    IS_DEFAULT = 'is_default'
+
     # el_klass (permit-target key) => model class name
     MODELS = {
       'reaction' => '::Reaction',
@@ -29,6 +34,13 @@ module Labimotion
       'cell_line' => '::CelllineSample'
     }.freeze
 
+    # Display names for the above, for screens that list the linkable types.
+    PERMIT_TARGET_LABELS = {
+      'reaction' => 'Reaction', 'sample' => 'Sample', 'molecule' => 'Molecule',
+      'wellplate' => 'Wellplate', 'screen' => 'Screen', 'research_plan' => 'Research Plan',
+      'device_description' => 'Device Description', 'cell_line' => 'Cell Line'
+    }.freeze
+
     # Curated, scalar columns exposed per type: [column/method, label, unit_column?]
     COLUMNS = {
       'reaction' => [
@@ -146,6 +158,107 @@ module Labimotion
       end
     end
 
+    # The attributes a user can pick for a klass with no element instance to read
+    # values from — the settings screen picks defaults before any link exists.
+    # Same shape as #available, minus 'value'/'value_system'.
+    def self.available_for_klass(el_klass)
+      el_klass = el_klass.to_s
+      return column_attributes_for_klass(el_klass) if MODELS.key?(el_klass)
+
+      klass = Labimotion::ElementKlass.find_by(name: el_klass)
+      klass.present? ? property_attributes_for_klass(klass) : []
+    end
+
+    # Remove attributes injected from a user's default (marked IS_DEFAULT by
+    # PropertiesEntity) from a properties hash on its way to the database. They
+    # are display-only: persisting them would freeze today's default into the
+    # element as an explicit per-instance selection, and a later change to the
+    # default would then stop reaching this link.
+    def self.strip_defaults(properties)
+      layers = properties.is_a?(Hash) ? properties[Labimotion::Prop::LAYERS] : nil
+      return properties unless layers.is_a?(Hash)
+
+      layers.each_value do |layer|
+        fields = layer.is_a?(Hash) ? layer[Labimotion::Prop::FIELDS] : nil
+        next unless fields.is_a?(Array)
+
+        fields.each { |field| strip_field_defaults(field) }
+      end
+      properties
+    end
+
+    def self.strip_field_defaults(field)
+      value = field.is_a?(Hash) ? field['value'] : nil
+      return unless value.is_a?(Hash)
+
+      attrs = value['el_attrs']
+      return unless attrs.is_a?(Array)
+
+      kept = attrs.reject { |attr| default_attr?(attr) }
+      return if kept.size == attrs.size # nothing injected — an explicit selection stays put
+
+      if kept.empty?
+        # Drop the key entirely so the field reads as "never picked" again and
+        # keeps following the user's default.
+        value.delete('el_attrs')
+      else
+        value['el_attrs'] = kept
+      end
+    end
+    private_class_method :strip_field_defaults
+
+    def self.default_attr?(attr)
+      attr.is_a?(Hash) && attr[IS_DEFAULT] == true
+    end
+    private_class_method :default_attr?
+
+    # The standard ELN types a drag field can link, for a settings screen that has
+    # to enumerate them. MODELS is the authority here, not the wider permit-target
+    # list: 'element' and 'generic_grid' are permit targets but not linkable types.
+    def self.permit_targets
+      MODELS.keys.map { |key| { 'key' => key, 'label' => PERMIT_TARGET_LABELS[key] || key.humanize } }
+    end
+
+    # Read off the released template rather than an instance, so the list matches
+    # what every element of the klass actually has.
+    def self.property_attributes_for_klass(klass)
+      layers = (klass.properties_release || {})[Labimotion::Prop::LAYERS] || {}
+      ordered = layers.values.sort_by { |layer| layer['position'] || 0 }
+      ordered.flat_map { |layer| layer_property_attributes(layer) }
+    end
+    private_class_method :property_attributes_for_klass
+
+    def self.layer_property_attributes(layer)
+      (layer[Labimotion::Prop::FIELDS] || []).filter_map do |field|
+        klass_property_attribute(layer, field) if PROPERTY_TYPES.include?(field['type'])
+      end
+    end
+    private_class_method :layer_property_attributes
+
+    def self.klass_property_attribute(layer, field)
+      {
+        'source' => SOURCE_PROPERTY,
+        'key' => "#{layer['key']}::#{field['field']}",
+        'label' => field['label'].presence || field['field'],
+        'type' => field['type'],
+        'group' => layer['label'].presence || layer['key']
+      }
+    end
+    private_class_method :klass_property_attribute
+
+    def self.column_attributes_for_klass(el_klass)
+      (COLUMNS[el_klass] || []).map do |col, label, _unit_col|
+        {
+          'source' => SOURCE_COLUMN,
+          'key' => col,
+          'label' => label.presence || col.to_s.humanize,
+          'type' => SOURCE_COLUMN,
+          'group' => el_klass
+        }
+      end
+    end
+    private_class_method :column_attributes_for_klass
+
     private
 
     def generic_klass?(name)

data/lib/labimotion/libs/sample_association.rb

@@ -70,7 +70,50 @@ module Labimotion
       []
     end
 
+    ## Link the generic elements referenced by drag_element table columns to the
+    ## owning element, mirroring what layer-level drag_element fields do below.
+    def self.build_table_element(field_tables, current_user, element = nil)
+      els = []
+      return els if element.nil?
+
+      field_tables.each do |field|
+        next unless field['sub_values'].present? && field[Labimotion::Prop::SUBFIELDS].present?
+
+        field_table_elements = field[Labimotion::Prop::SUBFIELDS].select { |ss| ss['type'] == Labimotion::FieldType::DRAG_ELEMENT }
+        next unless field_table_elements.present?
+
+        col_ids = field_table_elements.map { |x| x.values[0] }
+        col_ids.each do |col_id|
+          field['sub_values'].each do |sub_value|
+            next unless sub_value[col_id].present? && sub_value[col_id]['value'].present? && sub_value[col_id]['value']['el_id'].present?
+
+            svalue = sub_value[col_id]['value']
+            sid = svalue['el_id']
+            next if sid == element.id
+
+            # drag_element may link a standard element (reaction, cell_line, ...);
+            # el_id is then NOT a Labimotion::Element id, so an ElementsElement row
+            # would associate an unrelated generic element that shares the id.
+            next if Labimotion::LinkedElement::MODELS.key?(svalue['el_klass'].to_s)
+
+            el = Labimotion::Element.find_by(id: sid)
+            next if el.nil?
+
+            Labimotion::ElementsElement.find_or_create_by(parent_id: element.id, element_id: el.id)
+            els << el.id
+          end
+        end
+      end
+      els
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      []
+    end
+
     def self.update_sample_association(properties, current_user, element = nil)
+      # Every element and segment properties save funnels through here, which
+      # makes it the one place guaranteed to see the payload before it is stored.
+      Labimotion::LinkedElement.strip_defaults(properties)
       sds = []
       els = []
       properties[Labimotion::Prop::LAYERS].keys.each do |key|
@@ -99,7 +142,10 @@ module Labimotion
           Labimotion::ElementsSample.find_or_create_by(element_id: element.id, sample_id: subsample.id) if element.present?
         end
         field_tables = properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS].select { |ss| ss['type'] == Labimotion::FieldType::TABLE }
-        sds << Labimotion::SampleAssociation.build_table_sample(field_tables, current_user, element) if element.present?
+        if element.present?
+          sds << Labimotion::SampleAssociation.build_table_sample(field_tables, current_user, element)
+          els << Labimotion::SampleAssociation.build_table_element(field_tables, current_user, element)
+        end
         field_elements = layer[Labimotion::Prop::FIELDS].select { |ss| ss['type'] == Labimotion::FieldType::DRAG_ELEMENT }
         field_elements.each do |field|
           idx = properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS].index(field)

data/lib/labimotion/models/concerns/datasetable.rb

@@ -42,6 +42,9 @@ module Labimotion
       uuid = SecureRandom.uuid
       metadata = args[:metadata] || {}
       props = args[:properties]
+      # Datasets do not go through SampleAssociation, so they strip their own
+      # default-injected linked attributes before being stored.
+      Labimotion::LinkedElement.strip_defaults(props)
       props['pkg'] = Labimotion::Utils.pkg(props['pkg'])
       props['identifier'] = klass.identifier if klass.identifier.present?
       props['uuid'] = uuid

data/lib/labimotion/models/user_klass_setting.rb

@@ -1,12 +1,58 @@
 # frozen_string_literal: true
 
 module Labimotion
-  # Per-user, per-klass UI settings (e.g. toolbar Overview/Arrange visibility).
+  # Per-user, per-klass UI settings. Currently two of them, held side by side in
+  # the +settings+ jsonb:
+  #   * 'toolbar'         -> Overview/Arrange button visibility
+  #   * 'linked_el_attrs' -> the attributes that elements of this klass surface
+  #                          inline by default when linked from a drag field
+  #
   # Scoped to the owning user via created_by; at most one row per
   # (created_by, klass, klass_identifier) — see the unique index. Keyed on the
   # stable klass identifier so it applies to every instance of that klass,
   # across template versions.
   class UserKlassSetting < ApplicationRecord
+    # Generic templates are keyed by their klass model plus the stable klass
+    # identifier. Standard ELN elements (sample, reaction, ...) have no klass
+    # model, so they share the PERMIT_TARGET pseudo-type and use the permit-target
+    # key itself as the identifier — 'sample', 'reaction', ...
+    PERMIT_TARGET = Labimotion::Constants::Klass::PERMIT_TARGET
+
+    TOOLBAR = Labimotion::Constants::UserSetting::TOOLBAR
+    LINKED_EL_ATTRS = Labimotion::Constants::UserSetting::LINKED_EL_ATTRS
+
     self.table_name = :user_klass_settings
+
+    # All of a user's linked-attribute defaults, keyed by what a drag field stores
+    # in +el_klass+: a generic element klass *name*, or a permit-target key. Two
+    # queries for the whole map, so an element with many drag fields still costs
+    # the same as one with a single field.
+    def self.linked_el_attrs_by_el_klass(user_id)
+      return {} if user_id.blank?
+
+      rows = where(created_by: user_id, klass: [Labimotion::Constants::Klass::ELEMENT, PERMIT_TARGET]).to_a
+      rows.select! { |row| stored_linked_el_attrs(row).is_a?(Array) }
+      return {} if rows.empty?
+
+      names = element_klass_names(rows)
+      rows.each_with_object({}) do |row, acc|
+        el_klass = row.klass == PERMIT_TARGET ? row.klass_identifier : names[row.klass_identifier]
+        acc[el_klass] = stored_linked_el_attrs(row) if el_klass.present?
+      end
+    end
+
+    def self.stored_linked_el_attrs(row)
+      row.settings.is_a?(Hash) ? row.settings[LINKED_EL_ATTRS] : nil
+    end
+    private_class_method :stored_linked_el_attrs
+
+    # identifier => name, for the generic klasses among the given rows.
+    def self.element_klass_names(rows)
+      identifiers = rows.filter_map { |row| row.klass_identifier if row.klass == Labimotion::Constants::Klass::ELEMENT }
+      return {} if identifiers.empty?
+
+      Labimotion::ElementKlass.where(identifier: identifiers).pluck(:identifier, :name).to_h
+    end
+    private_class_method :element_klass_names
   end
 end

data/lib/labimotion/utils/export_utils.rb

@@ -156,6 +156,7 @@ module Labimotion
 
           set_table_prop(field, uuids, Labimotion::FieldType::DRAG_MOLECULE, &fetch_one)
           set_table_prop(field, uuids, Labimotion::FieldType::DRAG_SAMPLE, &fetch_one)
+          set_table_prop(field, uuids, Labimotion::FieldType::DRAG_ELEMENT, &fetch_one)
         end
         properties
       rescue StandardError => e

data/lib/labimotion/utils/import_utils.rb

@@ -120,7 +120,21 @@ module Labimotion
         properties
       end
 
-      def proc_table_prop(layer, key, data, instance, properties, field, tidx, type)
+      def proc_table_element(properties, instances, elements, svalue, key, tidx, vdx, col_id)
+        return properties unless id = svalue.fetch('el_id', nil)
+
+        att_el = (elements && elements[id]) || instances.fetch(Labimotion::Prop::L_ELEMENT, nil)&.fetch(id, nil)
+        return properties if att_el.nil?
+
+        val = properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][tidx]['sub_values'][vdx][col_id]['value']
+        properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][tidx]['sub_values'][vdx][col_id]['value'] = proc_assign_element(val, att_el)
+        properties
+      rescue StandardError => e
+        Labimotion.log_exception(e)
+        properties
+      end
+
+      def proc_table_prop(layer, key, data, instance, properties, field, tidx, type, elements = nil)
         fields = field[Labimotion::Prop::SUBFIELDS].select { |ss| ss['type'] == type }
         return properties if fields.nil?
 
@@ -141,6 +155,8 @@ module Labimotion
               properties = proc_table_molecule(properties, data, svalue, key, tidx, vdx, col_id)
             when Labimotion::FieldType::DRAG_SAMPLE
               properties = proc_table_sample(properties, data, instance, svalue, key, tidx, vdx, col_id)
+            when Labimotion::FieldType::DRAG_ELEMENT
+              properties = proc_table_element(properties, instance, elements, svalue, key, tidx, vdx, col_id)
             end
           end
         end
@@ -256,7 +272,7 @@ module Labimotion
     end
 
 
-    def self.proc_table(layer, key, data, instance, properties)
+    def self.proc_table(layer, key, data, instance, properties, elements = nil)
       fields = layer[Labimotion::Prop::FIELDS].select { |ss| ss['type'] == Labimotion::FieldType::TABLE }
       fields&.each do |field|
         tidx = layer[Labimotion::Prop::FIELDS].index(field)
@@ -264,6 +280,7 @@ module Labimotion
 
         proc_table_prop(layer, key, data, instance, properties, field, tidx, Labimotion::FieldType::DRAG_MOLECULE)
         proc_table_prop(layer, key, data, instance, properties, field, tidx, Labimotion::FieldType::DRAG_SAMPLE)
+        proc_table_prop(layer, key, data, instance, properties, field, tidx, Labimotion::FieldType::DRAG_ELEMENT, elements)
       end
       properties
     rescue StandardError => e
@@ -280,7 +297,7 @@ module Labimotion
         properties = proc_reaction(layer, key, data, instances, properties)
         properties = proc_sample(layer, key, data, instances, properties)
         properties = proc_element(layer, key, data, instances, properties, elements) # unless elements.nil?
-        properties = proc_table(layer, key, data, instances, properties)
+        properties = proc_table(layer, key, data, instances, properties, elements)
       end
       properties
     rescue StandardError => e

data/lib/labimotion/utils/serializer.rb

@@ -32,6 +32,30 @@ module Labimotion
       field
     end
 
+    ## Refresh the stored label/name of every drag_element cell of a table field.
+    ## Shared by PropertiesEntity and ElnElementEntity so all three loaders agree.
+    def self.set_table_element(field, field_table_elements)
+      col_ids = field_table_elements.map { |x| x.values[0] }
+      col_ids.each do |col_id|
+        field['sub_values'].each do |sub_value|
+          cell = sub_value[col_id]
+          next unless cell.present? && cell['value'].present? && cell['value']['el_id'].present?
+          ## A drag_element cell may link a standard ELN element (reaction, wellplate, ...);
+          ## el_id is then not a Labimotion::Element id, so keep what the client stored.
+          next if Labimotion::LinkedElement::MODELS.key?(cell['value']['el_klass'].to_s)
+
+          find_obj = Labimotion::Element.find_by(id: cell['value']['el_id'])
+          next if find_obj.blank?
+
+          cell['value']['el_label'] = find_obj.short_label
+          cell['value']['el_name'] = find_obj.name
+          cell['value']['el_tip'] = "#{find_obj.element_klass&.label}@@#{find_obj.name}"
+          cell['value']['icon_name'] = find_obj.element_klass&.icon_name || ''
+        end
+      end
+      field
+    end
+
     def self.element_properties(object)
       object.properties[Labimotion::Prop::LAYERS]&.keys.each do |key|
         # layer = object.properties[key]
@@ -72,6 +96,9 @@ module Labimotion
 
           field_table_samples = field[Labimotion::Prop::SUBFIELDS].select { |ss| ss['type'] == Labimotion::FieldType::DRAG_SAMPLE }
           object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] = set_table(field, field_table_samples, Labimotion::Prop::SAMPLE) if field_table_samples.present?
+
+          field_table_elements = field[Labimotion::Prop::SUBFIELDS].select { |ss| ss['type'] == Labimotion::FieldType::DRAG_ELEMENT }
+          object.properties[Labimotion::Prop::LAYERS][key][Labimotion::Prop::FIELDS][idx] = set_table_element(field, field_table_elements) if field_table_elements.present?
         end
       end
       object.properties

data/lib/labimotion/version.rb

@@ -2,5 +2,5 @@
 
 ## Labimotion Version
 module Labimotion
-  VERSION = '2.4.0.rc4'
+  VERSION = '2.4.0.rc6'
 end

data/lib/labimotion.rb

@@ -66,6 +66,7 @@ module Labimotion
   ######## Helpers
   autoload :GenericHelpers, 'labimotion/helpers/generic_helpers'
   autoload :ElementHelpers, 'labimotion/helpers/element_helpers'
+  autoload :CoverImageHelpers, 'labimotion/helpers/cover_image_helpers'
   autoload :SegmentHelpers, 'labimotion/helpers/segment_helpers'
   autoload :DatasetHelpers, 'labimotion/helpers/dataset_helpers'
   autoload :SearchHelpers, 'labimotion/helpers/search_helpers'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: labimotion
 version: !ruby/object:Gem::Version
-  version: 2.4.0.rc4
+  version: 2.4.0.rc6
 platform: ruby
 authors:
 - Chia-Lin Lin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-05 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: caxlsx
@@ -130,6 +130,7 @@ files:
 - lib/labimotion/entities/user_klass_setting_entity.rb
 - lib/labimotion/entities/vocabulary_entity.rb
 - lib/labimotion/helpers/converter_helpers.rb
+- lib/labimotion/helpers/cover_image_helpers.rb
 - lib/labimotion/helpers/dataset_helpers.rb
 - lib/labimotion/helpers/element_helpers.rb
 - lib/labimotion/helpers/exporter_helpers.rb