List indentation

[Witoso]

Provide a description of the task

Goal

Currently, we don’t accept margin on ul ol li . Depending on the configuration (GHS, indent, indent block) you will get different results.

Huuuge problem for import from Word incompatibility and migration from other HTML editors.

We need to be able to indent entire lists, independently of indenting their list items. Currently we have to do a bunch of hacks and patches to achieve this, so an upvote for supporting this in the core plugins!

Description

What is it?

• Loading or copy/pasting indented list causes list to lose indentation #6761

• IndentBlock breaks upcast of OL element's margin-left / Support margin for list li ol ul #16742

• Indent whole list when selection is inside the first list item #14383

• Notes

  Refinement notes

  • GHS stores this correctly (without IndentBlock)
  • separate plugin (which feature? indent or list package),
    • Tuning of indent block, so it’s not coupled with lists?
    • TBD
  • dedicated model attributes for margins and isFormatting for them
  • only remove format allows to remove it? Don’t touch decrease/increase?
    • when remove, by default it will remove all attributes of the items of the same list level
  • POC needed.

  Prev notes

  • accept (load/import/paste?) and properly place the margin when set on lists: ol ul and list items li (including multi-level lists)
    • potentially we could scope-cut the paste? But it wouldn’t make too much sense…
  • UI:
    • indent decrease removes the whole margin on the list item.
      • what if multiple items in the list item? Two paragraphs.
    • indent decrease removes the margin on the list, if selection is in the first item, index 0 (start of the list)??
  • indent right does nothing, no possibility to add those margin from the UI!

Scope:

Functional requirements:

• Supports bullet/numbered/multi-level/to do lists,
• whole list indentation (preservation + UX with the keyboard and toolbar)
• list item indentation (preservation + UX to remove with toolbar)

<ol style="margin-left:40px;">
    <li style="margin-left:50px;">
        asdasdasd
    </li>
    <li style="margin-left:60px;">
        asdasdasd
    </li>
</ol>

• UX allows indent/outdent lists

  • Support RTL
  • Keyboard
    • Indent scenario:
      • Selection: Collapsed or Touching the beginning, beginning of the first list item top of the list (not nested)
      • Trigger: TAB / Indent button
      • Result: Indent of the whole list increases.
    • Outdent scenario
      • Selection: Collapsed, beginning of the first list item top of the list (not nested)
      • Trigger: Only outdent button
      • Result: Indent of the whole list increases.

• UX to remove indent from list items - TBD is this useful (yes, one less GHS preservation?)

  • Selection: in the list item.
  • Trigger: Outdent
  • Condition: List item has its individual indent
  • Result: Whole indent of list item removed.

• Configuration

  • inherits from block indentation

• Preserve correctly import/paste scenarios with

  • “left” margins on lists
  • “left” margins on list items

<ol style="margin-left:40px;">
    <li style="margin-left:50px;">
        asdasdasd
    </li>
    <li style="margin-left:60px;">
        asdasdasd
    </li>
</ol>

Non-functional requirements:

• This is not about implementing skip-level lists
• Some of the actions mentioned here may be done later by Ruler, like indenting list items but we are not interested in it right now.

📃 Other details

• Browser: …
• OS: …
• CKEditor version: …
• Installed CKEditor plugins: …

[Witoso]

Research:

• padding or margin
• remove format checking (write down requirements)
• Paste from Office?

[Witoso]

@mmotyczynska jfyi, maybe research should include Paste from Office check.

[mmotyczynska]

1. Padding or Margin

After evaluating both options, I would recommend using margin rather than padding for representing list indentation. Key reasons include:

• Consistency with existing features:
  CKEditor already includes the IndentBlock feature, which applies indentation using margin. Using the same mechanism for lists maintains internal consistency.

• Alignment with external editors:
  Many tools from which users paste content - such as Microsoft Word and Google Docs - represent list indentation using margins.

• Integrator expectations:
  Partners who need explicit list indentation generally expect it to be set via margin-left, not padding.

• Visual behavior with background styling:
  When a list has a background applied, padding-based indentation introduces an empty colored area before the text, which is typically undesirable. Margins avoid this problem entirely.

The only downside is that Paste from Office currently maps indentation to padding. Switching to margin would require updating this mapping and would technically be a breaking change, but PFO should work correctly once the mapping is updated.

2. Remove Format

In the PoC, I introduced a new model attribute called listBlockIndent, marking it as a formatting attribute. This allowed removeFormat to behave as expected when the selection is inside a list:

• Executing Remove Format removes the listBlockIndent attribute.

• As a result, the list loses its indentation entirely.

3. Paste From Office

Our current PFO integration maps indentation from Word into padding. If we proceed with margin-based indentation:

• PFO would require a small adjustment to convert padding into margin.

• After this change, pasting content should work as expected.

If we chose padding instead in the implementation, PFO would work out of the box - but padding is a less suitable solution for list indentation.

Conclusion

• Margin is the preferred mechanism for representing list indentation.

• Remove Format should clear indentation by removing the listBlockIndent attribute.

• Paste from Office requires only a minor update if we standardize on margin. Otherwise, no changes are needed for padding.

[mmotyczynska]

Questions

1. Config (inheritance from IndentBlock)

   The ticket says this feature should inherit config from IndentBlock, but it doesn’t say that IndentBlock is required.

   • What happens when IndentBlock is not loaded?
   • Should integrators still define its config so we can reuse it?
   • Or is it meant only as an optional fallback?
   • Should we maybe consider a separate config option?

2. Keyboard shortcuts

   We add indent on TAB, but not outdent on Shift+TAB.

   • Why only one direction?
   • Is this intentional or should we think about supporting both?

3. Multi-item indentation

   Right now, the command is enabled only when selection is/starts at the first list item.

   • Should we support indenting multiple selected lists at once (like for example Word does)?

4. Indenting list items

   • Just to confirm: indenting list items is out of scope for now and planned later with Ruler?

[Witoso]

What happens when IndentBlock is not loaded?

I think list indentation is not possible in this case. The other approach is to allow lists to always indent, but I think it may be too big coupling.

We add indent on TAB, but not outdent on Shift+TAB.

Good catch, we should use shift+tab as well.

Should we support indenting multiple selected lists at once (like for example Word does)?

Good catch, I think in indent I can select and click the button for multiple paragraphs but not tab them.

Just to confirm: indenting list items is out of scope for now and planned later with Ruler?
Exactly, but we can do acceptance of the attribute (to not have GHS), and outdent / shift+tab that clears it.

[mmotyczynska]

I think list indentation is not possible in this case. The other approach is to allow lists to always indent, but I think it may be too big coupling.

Actually I implemented the second option in the PoC. List block indentation does not require IndentBlock at all. It doesn't even require the Indent plugin itself, although without it the toolbar buttons are missing, but the commands still work.

[Witoso]

Nice PoC:

• as for the coupling, hard for me to say. If list indentation doesn't require the indent block where would the configuration live then?
• Top of the head to check if such indentation is a keyboard trap? I think we have arrows available, so not.

[glynam1]

One ask I would have here from our customers is that it would be good to have the option to indent the list, but also have the option of indenting and taking the list markers from that indentation level.

This is common in situations where a list needs to be resumed after a table. e.g

With the current solution, it will still be confusing for customers who need to create the structure above.

One solution might be to allow non numeric characters in the list start numbering, which is currently disallowed

[Witoso]

@glynam1 thanks for the info. This request would be more in the scope of #11086 (rel a bit: #15874), as it's more about having a list item on a specific hierarchical level (with indent) than indentation itself. But the UI interaction will be interesting in the example you mentioned, as the first list item on an indent action will increase the margin, not the level.

[Witoso]

To discuss the config:

1. Is it steered by config or a plugin? Steering by config means this should be on by default, steering by plugin assumes it's off by default.
   • While ideally we would make it a default in core, historically we kept the core small, and properties are separated to achieve a more meaningful semantic editor with just List enabled. Decision: separated from Core.
2. Is this separated from IndentBlock (and Indent)
   • buttons come from this plugin.
   • Decision: IndentBlock.
3. Let's not distinguish between indentation of blocks and lists, same config.
4. List item indent research -- let's check how it behaves.

[mmotyczynska]

V2 of PoC.

• Added support for margin-left on list items.

• Added support for Shift+Tab.

• Implemented Paste from Office (with list indentation applied to the top-level list when possible, and remaining indentation applied to individual list items).

• Added support for margin-left on nested lists.

[Witoso]

👍 to check and validate during the implementation are: multi-level lists, Import from Word.