Skip to content

Instantly share code, notes, and snippets.

@felipenmoura

felipenmoura/HTML List Item Decorator Proposal.md

Last active February 17, 2018 18:25
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save felipenmoura/e99714c5f292c0ea957fea468656cfba to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save felipenmoura/e99714c5f292c0ea957fea468656cfba to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. felipenmoura revised this gist Feb 17, 2018. 1 changed file with 20 additions and 22 deletions.
    42 changes: 20 additions & 22 deletions HTML List Item Decorator Proposal.md
    View file
    Original file line number Diff line number Diff line change
    @@ -15,7 +15,7 @@
    + [Custom Elements](#custom-elements)
    * [Discussion](#discussion)

    ## About the proposal
    ### About the proposal

    I always wanted to be able to access and customize the bullets or numbers in HTML lists.

    @@ -55,21 +55,19 @@ By accessing `someListElement.decorator` we would have access to a _HTMLListIemD

    The developer will also be able to extend the decorator class used in a list, by setting the attribute `implements` in the list, pointing a _class_ in the current scope.

    #### Properties
    #### Properties:

    ```js
    {
    type: '' // (readonly) the list type, like number, circle, etc
    toString: '' // the value, like "C" or "34", or the utf8 symbol for Unordered lists
    value: '' // the value itself, like "C" or 34 (of type integer), or the utf8 symbol for Unordered lists
    index: 0 // the real index number of this item
    alt: ''// a readable value for screen readers
    separator: "." // the separator between the decorator and the list item content
    style: {} // a CSS style for that prticular bullet/number
    item: HTML_LISTITEM_ELEMENT // a reference to the list item this decorator is being applied to
    list: HTML_LIST_ELEMENT // a reference to the parent list element for this item
    }
    ```
    | Method | Description |
    |-----------|-------------|
    | type | (readonly) the list type, like number, circle, etc |
    | toString | the value, like "C" or "34", or the utf8 symbol for Unordered lists |
    | value | the value itself, like "C" or 34 (of type integer), or the utf8 symbol for Unordered lists |
    | index | the real index number of this item |
    | alt | a readable value for screen readers |
    | separator | the separator between the decorator and the list item content |
    | style | a CSS style for that prticular bullet/number |
    | item | a reference to the list item this decorator is being applied to |
    | list | a reference to the parent list element for this item |

    This way, developers would be able to customize that particular bullet or number, as well as read the current number, for example.

    @@ -83,13 +81,13 @@ If the decorator is an image, we would see its path in the _value_ (if image loa

    #### Methods

    | Method | Description | Arguments | Return |
    |---------|-------------|-----------|--------|
    | isLast | True if current listItem is the last in its list | -- | Boolean |
    | isFirst | True if current listItem is the first in its list | -- | Boolean |
    | isFallback | True if it was of type image, but failed loading the image | -- | `false` of the path for the image that failed |
    | getPrevious | Gets the previous decorator, or null if it is the first | -- | `HTMLListIemDecorator` |
    | getNext | Gets the next decorator, or null if this is the last one | -- | `HTMLListIemDecorator` |
    | Method | Description | Return |
    |---------|-------------|--------|
    | isLast | True if current listItem is the last in its list | Boolean |
    | isFirst | True if current listItem is the first in its list | Boolean |
    | isFallback | True if it was of type image, but failed loading the image | `false` of the path for the image that failed |
    | getPrevious | Gets the previous decorator, or null if it is the first | `HTMLListIemDecorator` |
    | getNext | Gets the next decorator, or null if this is the last one | `HTMLListIemDecorator` |

    ### Enters the HTMLListIemDecorator class

  2. felipenmoura revised this gist Feb 17, 2018. 1 changed file with 17 additions and 2 deletions.
    19 changes: 17 additions & 2 deletions HTML List Item Decorator Proposal.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,21 @@
    # HTML List Item Decorators

    ### About the proposal
    * [About the proposal](#about-the-proposal)
    * [The problem](#the-problem)
    + [Accessing the number](#accessing-the-number)
    * [The proposed solution](#the-proposed-solution)
    + [Decorators](#decorators)
    - [Properties](#properties)
    - [Methods](#methods)
    + [Enters the HTMLListIemDecorator class](#enters-the-htmllistiemdecorator-class)
    + [Styling](#styling)
    + [Accessibility](#accessibility)
    + [I18N](#i18n)
    + [Performance](#performance)
    + [Custom Elements](#custom-elements)
    * [Discussion](#discussion)

    ## About the proposal

    I always wanted to be able to access and customize the bullets or numbers in HTML lists.

    @@ -40,7 +55,7 @@ By accessing `someListElement.decorator` we would have access to a _HTMLListIemD

    The developer will also be able to extend the decorator class used in a list, by setting the attribute `implements` in the list, pointing a _class_ in the current scope.

    #### Properties:
    #### Properties

    ```js
    {
  3. felipenmoura revised this gist Feb 17, 2018. 1 changed file with 43 additions and 20 deletions.
    63 changes: 43 additions & 20 deletions HTML List Item Decorator Proposal.md
    View file
    Original file line number Diff line number Diff line change
    @@ -35,8 +35,10 @@ If I want a specific bullet or number to be in a different color or type, I can'

    ### Decorators

    I believe we could have access to something like decorators in in HTML_LIST_ELEMENT.
    By accessing someListElement.decorator we would have access to a HTML_LISTITEM_DECORATOR_ELEMENT instance.
    I believe we could have access to something like decorators in both _HTMLOListElement_ and _HTMLUListElement_.
    By accessing `someListElement.decorator` we would have access to a _HTMLListIemDecorator_ instance.

    The developer will also be able to extend the decorator class used in a list, by setting the attribute `implements` in the list, pointing a _class_ in the current scope.

    #### Properties:

    @@ -46,38 +48,40 @@ By accessing someListElement.decorator we would have access to a HTML_LISTITEM_D
    toString: '' // the value, like "C" or "34", or the utf8 symbol for Unordered lists
    value: '' // the value itself, like "C" or 34 (of type integer), or the utf8 symbol for Unordered lists
    index: 0 // the real index number of this item
    alt: ''// a readable value for screen readers
    separator: "." // the separator between the decorator and the list item content
    style: {} // a CSS style for that prticular bullet/number
    item: HTML_LISTITEM_ELEMENT // a reference to the list item this decorator is being applied to
    list: HTML_LIST_ELEMENT // a reference to the parent list element for this item
    }
    ```

    #### Methods

    | Method | Description | Arguments | Return |
    |---------|-------------|-----------|--------|
    | isLast | True if current listItem is the last in its list | -- | Boolean |
    | isFirst | True if current listItem is the first in its list | -- | Boolean |
    | isFallback | True if it was of type image, but failed loading the image | -- | `false` of the path for the image that failed |
    | getPrevious | Gets the previous decorator, or null if it is the first | -- | `HTML_LISTITEM_DECORATOR` |
    | getNext | Gets the next decorator, or null if this is the last one | -- | `HTML_LISTITEM_DECORATOR` |

    This way, developers would be able to customize that particular bullet or number, as well as read the current number, for example.

    ```js
    const dec = someOLItem.decorator // the decorator instance
    console.log(someOLItem.decorator) // 33, for example
    console.log(someULItem.decorator) // utf8 code for circle, for example
    ```

    If the decorator is an image, we would see its path in the _value_
    If the decorator is an image, we would see its path in the _value_ (if image loaded successfuly).

    #### Methods

    | Method | Description | Arguments | Return |
    |---------|-------------|-----------|--------|
    | isLast | True if current listItem is the last in its list | -- | Boolean |
    | isFirst | True if current listItem is the first in its list | -- | Boolean |
    | isFallback | True if it was of type image, but failed loading the image | -- | `false` of the path for the image that failed |
    | getPrevious | Gets the previous decorator, or null if it is the first | -- | `HTMLListIemDecorator` |
    | getNext | Gets the next decorator, or null if this is the last one | -- | `HTMLListIemDecorator` |

    ### Enters the HTML_LISTITEM_DECORATOR class
    ### Enters the HTMLListIemDecorator class

    We could have a HTML_LISTITEM_DECORATOR class that could be extended and implemented like so:
    We could have a HTMLListIemDecorator class that could be extended and implemented like so:

    ```js
    class myListIteDecorator extends HTML_LISTITEM_DECORATOR {
    class myListItemDecorator extends HTMLListIemDecorator {
    get () {
    return this.value
    }
    @@ -87,23 +91,26 @@ class myListIteDecorator extends HTML_LISTITEM_DECORATOR {
    And then (that's the part I'm really not comfortable with, yet)

    ```html
    <ol type="1" start="42" reversed implements="myListDecorator">
    <ol type="1" start="42" reversed implements="myListItemDecorator">
    ...
    </ol>
    ```

    That shall allow us to do something like this, for an useful example:

    ```js
    class qAndA extends HTML_LISTITEM_DECORATOR {
    class qAndA extends HTMLListIemDecorator {
    get () {
    if (this.index % 2 === 0) {
    // even
    this.value = "A"
    this.separator = ': '
    this.alt = 'Answer'
    } else {
    // odd
    this.value = "Q" + this.value
    const questionNumber = Math.ceil(this.index / 2)
    this.alt = "Question " + questionNumber
    this.value = "Q" + questionNumber
    this.separator = ') '
    this.style.fontWeight = 'bold'
    }
    @@ -158,6 +165,17 @@ The `decorator` pseudo element:
    }
    ```

    ### Accessibility

    The accessibility should be enhanced by using a _alt_ in the decorators.
    For instance, a screen reader could read "Question 1" instead of "1" or "Q1" in the _qAndA_ example above.

    ### I18N

    Internationalization can also be accomplished by reading the lang attribute in the list element or the page and using it to determine which label should be used in the decorator.

    Note that this could even allow you to use _Date Objects_ as your list decorators, assuming you customized them in your class extension.

    ### Performance

    Although it looks like an HTML element, it will not repaint or redraw in different moments.
    @@ -169,7 +187,7 @@ In order to redraw a decorator, something that reflects into it should be change
    For example, if you have the following implementation:

    ```js
    class todoList extends HTML_LISTITEM_DECORATOR {
    class todoList extends HTMLListIemDecorator {
    get () {
    if (this.item.classList.has('done')) {
    // even
    @@ -199,6 +217,11 @@ listItem.addEventListener('click', event => {
    })
    ```

    ### Custom Elements

    You can create your own _Custom Elements_ to implement the your customized class for your decorators.
    This allows you to have a seprate scope protecting your variables and keeping your code more organized.

    ## Discussion

    Feel free to leave your comments in the [GIST of this proposal](https://gist.github.com/felipenmoura/e99714c5f292c0ea957fea468656cfba/).
  4. felipenmoura revised this gist Feb 17, 2018. 1 changed file with 94 additions and 12 deletions.
    106 changes: 94 additions & 12 deletions HTML List Item Decorator Proposal.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,7 @@
    # HTML List Item Decorators

    ### About the proposal

    I always wanted to be able to access and customize the bullets or numbers in HTML lists.

    For example...in the following list:
    @@ -15,6 +17,8 @@ For example...in the following list:
    </ol>
    ```

    This proposal will also work well when _appending_, _prepending_ or _replacing_ childs in lists.

    ## The problem

    ### Accessing the number
    @@ -27,32 +31,47 @@ Decorating bullets/numbers
    If I want a specific bullet or number to be in a different color or type, I can't.


    ### The proposed solution
    ## The proposed solution

    ## Decorators
    ### Decorators

    I believe we could have access to something like decorators in in HTML_LIST_ELEMENT.
    By accessing someListElement.decorator we would have access to a HTML_LISTITEM_DECORATOR_ELEMENT instance.

    This could contain:
    #### Properties:

    ```js
    {
    type: '' // the list type, like number, circle, etc
    type: '' // (readonly) the list type, like number, circle, etc
    toString: '' // the value, like "C" or "34", or the utf8 symbol for Unordered lists
    value: '' // the value itself, like "C" or 34 (of type integer), or the utf8 symbol for Unordered lists
    index: 0 // the real index number of this item
    separator: "." // the separator between the decorator and the list item content
    style: {} // a CSS style for that prticular bullet/number
    item: HTML_LISTITEM_ELEMENT // a reference to the list item this decorator is being applied to
    list: HTML_LIST_ELEMENT // a reference to the parent list element for this item
    }
    ```

    #### Methods

    | Method | Description | Arguments | Return |
    |---------|-------------|-----------|--------|
    | isLast | True if current listItem is the last in its list | -- | Boolean |
    | isFirst | True if current listItem is the first in its list | -- | Boolean |
    | isFallback | True if it was of type image, but failed loading the image | -- | `false` of the path for the image that failed |
    | getPrevious | Gets the previous decorator, or null if it is the first | -- | `HTML_LISTITEM_DECORATOR` |
    | getNext | Gets the next decorator, or null if this is the last one | -- | `HTML_LISTITEM_DECORATOR` |

    This way, developers would be able to customize that particular bullet or number, as well as read the current number, for example.

    ```js
    console.log(someOLItem.decorator) // 33, for example
    console.log(someULItem.decorator) // utf8 code for circle, for example
    ```

    If the decorator is an image, we would see its path in the _value_

    ### Enters the HTML_LISTITEM_DECORATOR class

    We could have a HTML_LISTITEM_DECORATOR class that could be extended and implemented like so:
    @@ -78,7 +97,7 @@ That shall allow us to do something like this, for an useful example:
    ```js
    class qAndA extends HTML_LISTITEM_DECORATOR {
    get () {
    if (this.value % 2 === 0) {
    if (this.index % 2 === 0) {
    // even
    this.value = "A"
    this.separator = ': '
    @@ -108,15 +127,78 @@ Then, we could use it like this:

    And see as the result:


    **Q1) Is the Earth flat?**
    A: Nope, it isn't!
    **Q2) Why is six affraid of seven?**
    A: Because seven eight nine
    **Q3) Why did the chicken cross the street?**
    A: Because it was bored

    > And in that example, the questions should be bold
    ### Styling

    Styling wouldn't change a bit, as we already have some basic style properties to work with, like "list-style-position", "list-style-type" and "list-style-image".

    The difference is that now, we can customize it decorators one by one or, use a `pseudo-element` for that.
    The `decorator` pseudo element:

    ```css
    .someList:decorator {
    color: red;
    }

    .someList li:nth-child(3):decorator {
    color: blue;
    }

    .someList li:first-child:decorator:before {
    content: "Follow these steps";
    }
    ```

    ### Performance

    Although it looks like an HTML element, it will not repaint or redraw in different moments.

    For example, changing the `innerHTML` or `innerText` of a decorator should not work as it is merely a decorator for its list item.

    In order to redraw a decorator, something that reflects into it should be changed in the list item it's related to.

    For example, if you have the following implementation:

    ```js
    class todoList extends HTML_LISTITEM_DECORATOR {
    get () {
    if (this.item.classList.has('done')) {
    // even
    this.style.color = '#f0f0f0'
    }
    return this
    }
    }
    ```
    Q1) Is the Earth flat?
    A: Nope, it isn't!
    Q2) Why is six affraid of seven?
    A: Because seven eight nine
    Q3) Why did the chicken cross the street?
    A: Because it was bored

    You could update the decorator style by adding or removing the class "done" in your list items:

    ```html
    <ol type="1" implements="todoList">
    <li class="done">Buy bread</li>
    <li>Buy milk</li>
    <li class="done">Aniversary</li>
    <li>Pay bills</li>
    <li>Send some important e-mail</li>
    <li>Call mom</li>
    </ol>
    ```

    > And in that example, the questions should be bold
    ```js
    listItem.addEventListener('click', event => {
    this.classList.toggle('done')
    })
    ```

    ## Discussion

    Feel free to leave your comments in the [GIST of this proposal](https://gist.github.com/felipenmoura/e99714c5f292c0ea957fea468656cfba/).
  5. felipenmoura created this gist Feb 17, 2018.
    122 changes: 122 additions & 0 deletions HTML List Item Decorator Proposal.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,122 @@
    # HTML List Item Decorators

    I always wanted to be able to access and customize the bullets or numbers in HTML lists.

    For example...in the following list:

    ```html
    <ol type="1" start="42" reversed>
    <li>AAA</li>
    <li>BBB</li>
    <li>CCC</li>
    <li>DDD</li>
    <li>EEE</li>
    <li>FFF</li>
    </ol>
    ```

    ## The problem

    ### Accessing the number

    The user can see the number in the list, but if I want to know the number of the item the user has clicked, for example, I have to count their previous siblings. And have to think about reverse and start as well.
    And all that ignoring other things like "list-style-position", "list-style-type" and "list-style-image", which would apply different rules using css, instead of HTML attributes.

    Decorating bullets/numbers

    If I want a specific bullet or number to be in a different color or type, I can't.


    ### The proposed solution

    ## Decorators

    I believe we could have access to something like decorators in in HTML_LIST_ELEMENT.
    By accessing someListElement.decorator we would have access to a HTML_LISTITEM_DECORATOR_ELEMENT instance.

    This could contain:

    ```js
    {
    type: '' // the list type, like number, circle, etc
    toString: '' // the value, like "C" or "34", or the utf8 symbol for Unordered lists
    value: '' // the value itself, like "C" or 34 (of type integer), or the utf8 symbol for Unordered lists
    separator: "." // the separator between the decorator and the list item content
    style: {} // a CSS style for that prticular bullet/number
    }
    ```

    This way, developers would be able to customize that particular bullet or number, as well as read the current number, for example.

    ```js
    console.log(someOLItem.decorator) // 33, for example
    console.log(someULItem.decorator) // utf8 code for circle, for example
    ```

    ### Enters the HTML_LISTITEM_DECORATOR class

    We could have a HTML_LISTITEM_DECORATOR class that could be extended and implemented like so:

    ```js
    class myListIteDecorator extends HTML_LISTITEM_DECORATOR {
    get () {
    return this.value
    }
    }
    ```

    And then (that's the part I'm really not comfortable with, yet)

    ```html
    <ol type="1" start="42" reversed implements="myListDecorator">
    ...
    </ol>
    ```

    That shall allow us to do something like this, for an useful example:

    ```js
    class qAndA extends HTML_LISTITEM_DECORATOR {
    get () {
    if (this.value % 2 === 0) {
    // even
    this.value = "A"
    this.separator = ': '
    } else {
    // odd
    this.value = "Q" + this.value
    this.separator = ') '
    this.style.fontWeight = 'bold'
    }
    return this
    }
    }
    ```

    Then, we could use it like this:

    ```html
    <ol type="1" implements="qAndA">
    <li>Is the Earth flat?</li>
    <li>Nope, it isn't!</li>
    <li>Why is six affraid of seven?</li>
    <li>Because seven eight nine</li>
    <li>Why did the chicken cross the street?</li>
    <li>Because it was bored</li>
    </ol>
    ```

    And see as the result:

    ```
    Q1) Is the Earth flat?
    A: Nope, it isn't!
    Q2) Why is six affraid of seven?
    A: Because seven eight nine
    Q3) Why did the chicken cross the street?
    A: Because it was bored
    ```

    > And in that example, the questions should be bold