Bulleted/numbered lines and indentations

[matus-z-ceros]

Add support for bulleted/numbered lines (a.k.a. unordered/ordered lists) and tab indentations.
The spec should enable line indentations without the bullet/number - e.g. the first line of a paragraph which is indented by a single tab.

These are related to the Text structure and should be nested under it.

Proposal 1 - A map from line numbers to line styles

"text": {
    ...,
    "lines": {
        "0": {
            "indentation": 1
        },
        "2": {
            "type": "ORDERED",
            "indentation": 1
        },
        "3": {
            "type": "ORDERED",
            "indentation": 1
        },
        "4": {
            "type": "ORDERED",
            "indentation": 1
        }
    }
} 

• The approach saves data by skipping default values which are { "type": "NORMAL", "indentation": 0 }.

Proposal 2 - An array of ranged line styles

"text": {
    ...,
    "lines": [
        {
            "line": {
                "type": "NONE",
                "indentation": 1
            },
            "ranges": {
                {
                    "from": 0,
                    "to": 1
                }
            }
        },
        {
            "line": {
                "type": "ORDERED",
                "indentation": 1
            },
            "ranges": {
                {
                    "from": 2,
                    "to": 5
                }
            }
        }
    ]
}

• This approach uses a Range sub-structure similarly to the StyleRange structure.

[matus-z-ceros]

@cerosnikita - The "Proposal 1" is the result of our brainstorming. Add any additional comments/ideas.

@Chlumsky-Ceros - Do you have any alternative solutions? Could you list their benefits?

[Chlumsky-Ceros]

First of all, you keep using "lines" when referring to paragraphs. The naming has to be accurate.

I am also against using number strings as keys in JSON objects.

From my understanding, we basically want per-paragraph attributes that are currently global for the entire text, so a possible way to do this would be, instead of text value:

    "text": {
        "defaultStyle": { },
        "defaultParagraphStyle": {
            "horizontalAlign": "LEFT",
            "leftPadding": 0,
            "rightPadding": 0,
            "topPadding": 0,
            "firstLineIndent": 0,
            "listStyle": "NONE"
        },
        "paragraphs": [
            {
                "string": "Item 1 text",
                "paragraphStyle": {
                    "listStyle": "BULLET",
                    "leftPadding": 4.5
                },
                "styles": []
            },
            {
                "string": "Item 2 text",
                "paragraphStyle": {
                    "listStyle": "BULLET",
                    "leftPadding": 4.5
                },
                "styles": []
            }
        ]
    }

For simple text, paragraph would contain just one element. This way we could also get rid of the non-standard paragraph separators.

[cerosnikita]

First of all, you keep using "lines" when referring to paragraphs. The naming has to be accurate.

Very good point, actually. I thought that it's divided just with regular line break.

I am also against using number strings as keys in JSON objects.

Why? It should save some bytes in most cases. Figma uses same approach, btw.

From my understanding, we basically want per-paragraph attributes that are currently global for the entire text, so a possible way to do this would be, instead of text value:

Looks okay to me, but the problem is that this is breaking change, because, if I understand correctly, you move styles from Text descriptor to paragraphs entries. As an alternative we can use something what Figma use: mark characters with paragraph ids, something like:

{
  paragraphsChars: [0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, ...],
  paragraphs: {
    '0': { /* paragraph's style descriptor for first 5 chars in the text */ },
    '1': { /* paragraph's style descriptor for 5-10 chars in the text */ },
    ...
  }
}

This approach looks meh and unnecessary complicates format. So I'd rather use yours, but I am not sure if it's still okay to change because Xara already works on texts.

[matus-z-ceros]

Agreed with the naming "paragraph" 👍

Also interested about the reasoning against numerical keys. Is this because then the keys wouldn't correspond to the name of a sub-structure of struct Paragraph?

@Chlumsky-Ceros Your approach of splitting the text to paragraphs and setting up per-paragraph attributes looks good to me, and more organized than the Figma style. I suppose an alternative for the per-paragraph styles would be to keep them under text. In that case adding paragraph index would be necessary. E.g.:

"text": {
    "defaultStyle": {},
    "defaultParagraphStyle": {},
    "paragraphs": [
        {
            "string": "Item 1 text",
            "paragraphStyle": {
                "listStyle": "BULLET",
                "leftPadding": 4.5
            }
        },
        {
            "string": "Item 2 text",
            "paragraphStyle": {
                "listStyle": "BULLET",
                "leftPadding": 4.5
            }
        }
    ],
    "styles": [
        {
            "style": {},
            "ranges": [
                {
                    "paragraph": 0,
                    "from": 0,
                    "to": 5
                },
                {
                    "paragraph": 1,
                    "from": 0,
                    "to": 5
                }
            ]
        }
    ]
}

We would also save some data in case there is a small number of styles shared across a large number of paragraphs.

[matus-z-ceros]

Btw. What's the reason for skipping bottomPadding? Figma has it.

[Chlumsky-Ceros]

Yes, my proposal would be breaking but I don't see a good way to properly do this in a backwards-compatible way.

I do like the modification of style ranges as

{
    "paragraph": 0,
    "from": 0,
    "to": 5
}

I am not against including bottom padding, I just thought it was unnecessary.

[cerosnikita]

@matus-z-ceros your alternative solution is also nice. But seems breaking too because text content is moved into paragraphs elements. I am not sure if it's okay to tell Xara to change things a little bit, though. I'll try to ask it tomorrow.

Anyway, am I right that Viktor's and Matus's solutions are pretty much same with the only difference how intersection of two multiples is handled? In Viktor's we go through paragraphs and find all corresponding styles and in Matus's we go through styles where each style is connected to corresponding paragraph, yep?

[matus-z-ceros]

My solution is an adaptation of Viktor's. I agree that splitting the text to paragraphs is a good idea.

The difference is that in my adaptation styles are shared across paragraphs (the overhead being having to specify the "paragraph" value for each style range), whereas in Viktor's styles are per-paragraph, which may result in duplicated styles.

Ok, let's find out if Xara would be okay with a breaking change.