Docs: select option documentation is unclear

[ggorlen]

Increasing Access

Better documenting the confusing behavior of <select> / <option> can help beginners new to coding avoid gotchas that can lead to frustration.

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build Process
• Unit Testing
• Internalization
• Friendly Errors
• Other (specify if possible)

Feature enhancement details

See #1969 (comment) for an in-depth contextual explanation of a lack of unique <option> element text contents leading to undefined and causing a confusing situation for a student.

We should more clearly document that <option> text contents are expected to be unique--when .option(optionName) is called with non-unique values, rather than new options being added as expected, existing options' values are set to undefined.

A minimal example is:

function setup() {
  const select = createSelect();
  select.option("a");
  select.option("a");
}

Here, one might expect a dropdown with two "a" elements, but instead, one <option> is created with value="undefined" rather than value="a":

<select>
  <option value="undefined">a</option>
</select>

Contrast this to comparable native DOM code:

const select = document.createElement("select");
document.body.appendChild(select);
const option0 = document.createElement("option");
option0.textContent = option0.value = "a";
const option1 = document.createElement("option");
option1.textContent = option1.value = "a";
select.append(option0, option1);

Which creates the unsurprising:

<select>
  <option value="a">a</option>
  <option value="a">a</option>
</select>

[welcome]

Welcome! 👋 Thanks for opening your first issue here! And to ensure the community is able to respond to your issue, please make sure to fill out the inputs in the issue forms. Thank you!

[Qianqianye]

Thanks @ggorlen. I am adding the DOM stewards @outofambit, @SarveshLimaye, @SamirDhoke to this discussion.

[SamirDhoke]

Thanks @Qianqianye for adding me to this discussion. @ggorlen I want to understand whether we want to add two options with same name and value when called select.option() twice or just replace the value of the existing option, if any ?

[ggorlen]

@ggorlen I want to understand whether we want to add two options with same name and value when called select.option() twice or just replace the value of the existing option, if any ?

Well, the existing approach is to change the value of the existing option, which seems to have originally been discussed in #1554 and implemented in #1969.

I responded to that pull here explaining that the design choice seems to lead to various bugs and (to my mind) surprising behavior.

My personal opinion is that the way the option was implemented was prolematic from the start. It's an unusual design choice to impose that select option text be unique and I think there are better ways to enable value changes that don't treat the text content as a unique identifier.

But stopping short of revisiting the design that's been in the code since 2017, the goal of this PR is to simply clarify the existing option behavior so as to make it more obvious to a casual user. While my mentee and I were trying to figure out what was wrong with our code, we checked the docs but there was no obvious indication of the uniqueness behavior or HTML special characters (probably a bug in its own right, see #5778), and wound up in the p5 source code to figure it all out.

Kind of long-winded (sorry!), but hopefully this answers the question.

[SamirDhoke]

Yes. sorry i didn't see the pull request first, it's one of my very first contribution conversations. Thanks for pointing out the links, it helped me to understand the solution.