feat: Add developer tools for ID discovery

[palkerecsenyi]

Closes #22

Part of inveniosoftware/invenio-app-rdm#3100

---

• Added a global (window-level) function reactOverridableDevMode that, when called, enables a "developer mode" in which all overridable elements show a small tag with their ID. This helps simplify ID discovery by removing the need for manually searching through a potentially large codebase.

  Kooha-2025-07-25-13-26-15.webm

• This change ensures that the DOM is completely unaffected when dev mode is not enabled, avoiding a major/breaking change to the library.

  • For example, wrapping the child in a <div> with position: relative and then showing a position: absolute ID tag when hovered would significantly reduce the complexity of my implementation, but this has the risk of breaking designs that e.g. apply a fixed amount of margin between each child in a list, or overridables within HTML tables.

• It also avoids a full re-render of the child element when dev mode gets enabled, which otherwise may cause errors with older components that are not built to handle immediate unmount-remount cycles.

  • While allowing full re-renders would make this solution significantly simpler, I found this to cause full-page crashes on InvenioRDM when enabling devmode. Well-built React components are technically supposed to handle this without issues, but we have some slightly older ones that import non-React libraries such as TinyMCE and as such have complex unexpected side-effects when rendering.

• A small algorithm ensures that the ID tags do not overlap (or at least they don't overlap too much) but the nested ordering might not be preserved. For example, a deeper nested overridable in the same location might be shown higher up than a shallower one. The placing of tightly clustered ID tags is somewhat random and depends on the internal order of execution within React.

• The ID tags can be clicked to copy their content to the clipboard

  Kooha-2025-07-25-13-30-29.webm

• This currently has two limitations: These limitations have now been fixed.

  1. Some areas on the page with lots of densely nested overridables may cause overlapping ID tags to be rendered which is hard to read

     See example

     

  2. Due to the absolute top-level rendering of the ID tags they are not pointer-interactive and their text can't be selected or copied. The developer has to manually type the ID into their IDE.

• For now I have used inline style objects where needed instead of CSS, to avoid adding a PostCSS step to rollup which might add too much complexity. However, I'm happy to change this if we think it will look neater.

• I have thoroughly tested this on InvenioRDM. Also confirmed to be working on Indico:

  Kooha-2025-07-24-10-29-41.webm

[ntarocco]

Looks great! Quick question: I did not fully understand this part

Due to the absolute top-level rendering of the ID tags they are not pointer-interactive and their text can't be selected or copied.

It looks like that you are showing them on hover/mousemove, or am I wrong?
I was wondering if it was possible/easy to add a border to the entire component, so that it would be easier to identify the area of the component.

[palkerecsenyi]

Looks great! Quick question: I did not fully understand this part

Due to the absolute top-level rendering of the ID tags they are not pointer-interactive and their text can't be selected or copied.

It looks like that you are showing them on hover/mousemove, or am I wrong? I was wondering if it was possible/easy to add a border to the entire component, so that it would be easier to identify the area of the component.

We are showing/hiding based on hover over the parent element of the overridable one. This is because we place a <span> just before the overridable element and attach a ref to it, so it's easy to get a DOM reference to the parent. It's more difficult to get a reference to the actual element since we don't know where in the DOM it is; even if we know we've placed a span before it, the element could be a <></> so we cannot simply look at the 'next' node after the span.

As such, we don't know exactly which overridable the user is hovering over, just the common parent of multiple elements. If we implemented a copy-to-clipboard feature for example, we wouldn't know exactly which ID to copy.

Also, wrapping the component with a border would be somewhat difficult too, as this would potentially require some sort of container to wrap it (e.g. a div), meaning a full re-render is required when dev mode is activated, causing the errors I mentioned before.

[ThiefMaster]

Do you have a dev instance where your PR is running right now (if it's just accessible from inside CERN that's fine)? I'd just like to try it out w/o the hassle of updating it on my local Indico instance.

[palkerecsenyi]

Do you have a dev instance where your PR is running right now (if it's just accessible from inside CERN that's fine)? I'd just like to try it out w/o the hassle of updating it on my local Indico instance.

Not at the moment but I'm happy to set one up today

[tomasr8]

LGTM, I just had this last suggestion #23 (comment) which could make it a bit faster but it's not necessary

[palkerecsenyi]

LGTM, I just had this last suggestion #23 (comment) which could make it a bit faster but it's not necessary

Apologies, I didn't notice your comment! I'll work on this now :)