Research UX/UI options for the UI of the "Allow setting start/reversed options of lists"

[Reinmar]

Random notes:

• Part of the Implement ordered lists start index and reverse order options #1032 epic.
• Separate plugin (ListProperties?).
• Most likely to be placed in the same dropdown that we use for ListStyles.
• Separated from the current content of ListStyles with some separator.
• 3 cases to consider: list styles + list props coexisting together, list props only, list styles only.
• How should the input for the start look? Just input, or +/-. Most likely, for now: KISS.
• Place for validation message?
• Off-topic: Autoformat's support for "3. " -> followup.
• We want to avoid the problem that we faced in the dropdown for inserting images via URL which became unclear.

[oleq]

The breakdown of the list options feature goes as follows:

• UI designs
• Engine layer
• UI layer
• Granular tasks (that can be estimated)

UI designs (proposal)

Just list styles

Note: Added some space around thumbnails. ATM they are crowded. Spacings should be unified across the UI (link form, table props, find and replace have the same spacing).

Just numbered list options

Both features side-by-side

Note: To create some space for list options labels/inputs (long in some languages), the panel needs to be wider.

Note: List options should not change the center of gravity in this form (misc feature). Most of the users will still go there just to change the type of the list.

Note: Fancy buttons next to the number input are optional (follow-up, explained below). We can go with native ones at the beginning.

Technical layer: engine

• (new 🌱) ListNumberedOptionsEditing
  • Registers the listReversed attribute on listItem
  • Registers the listStart attribute on listItem
  • Registers a model post-fixer to do the magic similar to fixListStyleAttributeOnListItemElements()
  • Registers listeners to clean-up listReversed and listStart attributes when the list type changes (similar to the ones in ListStyleEditing)
  • Registers listeners to reset listReversed and listStart so they don't propagate when indenting and outdenting lists.
  • Implements listReversed and listStart attributes handling when merging lists.
  • Model post-fixer to satisfy integration with to-do lists.
  • Opinion: That's a lot of code and tests 👆
  • Question: How do we avoid duplicating a lot of code? Is there any way to share some of the logic?
• (new 🌱) ListNumberedOptionsCommand
  • A command to set listReversed and listStart attributes on a list.
  • It should accept values as execute() options.
  • It should have a dynamic isEnabled state so that the UI can enable/disable when changing these attributes is possible/impossible.
  • It should have a dynamic value so that the UI can bind to it.

Technical layer: UI

Current UI architecture

• List
  • ListUI
    • creates 'bulletedList' and 'numberedList' toolbar buttons
• ListStyle
  • ListStyleUI
    • overrides 'bulletedList' and 'numberedList' buttons with dropdowns with styles

New UI architecture

• List
  • ListUI
    • creates 'bulletedList' and 'numberedList' toolbar buttons
• ListStyle
  • (new 🌱) class NumberedListFormView extends View
    • It will create a <div class="ck-numbered-list-form">...</div>
    • It will initialize NumberedListFormView#children so ListStyleUI and ListNumberedOptionsUI can inject their UI there
    • It will initialize a FocusTracker+cycler so ListStyleUI and ListNumberedOptionsUI can register their UI components.
    • It is empty by default.
  • ListStyleUI
    • Overrides 'bulletedList' button with a dropdown with styles.
    • Detects the type of 'numberedList' component.
      • ButtonView → overrides 'numberedList' button with a DropdownView with styles.
        • Injects a new NumberedListFormView into the dropdown
      • DropdownView → injects the styles UI into the 'numberedList' dropdown (precisely: into NumberedListFormView inside created by ListNumberedOptionsUI).
    • Adds the ck-list-style-dropdown class to the dropdown.
• (new 🌱) ListNumberedOptions extends Plugin
  • (new 🌱) ListNumberedOptionsUI extends Plugin
    • (new 🌱) ListNumberedOptionsFormView extends View
      • The form that comes with
        • The "List options" collapse button,
        • The list start number input created with createLabeledInputNumber(),
        • The reversed toggle switch (SwitchButtonView),
        • Both the input and the toggle should be disabled together with ListNumberedOptionsCommand so it is impossible to mess with them when, for instance, an unordered list is selected or a paragraph.
    • Detects the type of 'numberedList' component.
      • ButtonView → overrides 'numberedList' button with a dropdown with options
        • Injects a new NumberedListForm into the dropdown
      • DropdownView → injects the options UI into the 'numberedList' dropdown (precisely: into NumberedListForm inside created by ListStyleUI).
    • Adds the ck-list-numbered-options-dropdown class to the dropdown
• ckeditor5-ui
  • (new 🌱) InputNumberView extends View
    • It should have min, max, and step observables and bind them to the <input type="number" />. More on MDN.
    • Depending on the time available: we either go with the browser implementation of the increment/decrement buttons or we implement fancy buttons like in the design.
  • (new 🌱) createLabeledInputNumber() (similar to createLabeledInputText())
    • an easy creator for InputNumberView instances

What the CSS classes are for?

• If the .ck-list-style-dropdown is alone
  • the NumberedListForm will be narrower (3x2)
• If the .ck-list-numbered-options-dropdown is alone
  • The NumberedListForm will be wider (good for labels and the input),
  • The "List options" collapse button will be hidden,
  • Fields will be always visible.
• If both classes are present,
  • The NumberedListForm will be wider (good for labels and the input),
  • The "List options" collapse button will be visible,
  • The fields will be hidden under the collapse button.
    • Note: ListNumberedOptionsUI must manipulate the focus tracker/cycler if some of the fields disappear for proper focus management and a11y.

Miscellaneous

• getSplitButtonCreator()
  • It would work fine for 'bulletedList' because nothing changes there.
  • Does not make sense for 'numberedList' anymore. It needs a flexible form view that can host styles UI and/or options UI.
  • The bottom line is, we should make it more generic
    • It will create a dropdown, bind it to the command, etc. but it will omit the creation of styles and adding a toolbar to the dropdown. That will become the responsibility of ListStyleUI. Not much work, though.
• (new/optional 🌱) createNumberedListForm()
  • this kind of helper would simplify the common code in ListStyleUI and ListNumberedOptionsUI. The helper would create the NumberedListForm, bind things, etc.

Tasks

1. Implement the editing part (ListNumberedOptionsEditing + ListNumberedOptionsCommand) with tests
2. Implement the UI part (NumberedListFormView + ListNumberedOptions + ListNumberedOptionsUI + ListNumberedOptionsFormView + InputNumberView (basic) + changes in ListStyleUI + helpers) with tests.
   1. depends on the editing part
3. Docs: Update the "Lists" guide, create the new section next to https://ckeditor5.github.io/docs/nightly/ckeditor5/latest/features/lists/lists.html#list-styles and update the rest of the guide (intro, common API)
   1. depends on the editing part
   2. depends on the UI part
4. (Optional) Enhance the InputNumberView with fancy buttons (could be a follow-up)
   1. depends on the UI part