Allow new props for Ordered/Unordered List components

[stern-shawn]

Hi team!

Awhile ago we got a request from the Flex team to follow Google's docs standards for sublists and render nested ordered lists using a cycling rotation of list style types (numeric, alphabetical, roman numerals, back to numeric, etc). This isn't possible with Paste out of the box (as far as we can tell) because the OrderedList component hardcodes listStyleType and doesn't expose it as a configurable prop. Not wanting to raise a stink because we saw the old issue with Flex's autogenerated docs that is the cause for them being hardcoded initially, we just spun up a copy of OrderedList but with flexible input props that we then control based on the logical depth of a given list:

import * as React from 'react';
import { OrderedListProps, List } from '@twilio-paste/core/list';
import { safelySpreadTextProps } from '@twilio-paste/core/text';
import { ListStyleType } from '@twilio-paste/core/style-props';

const listStyleMap: Record<NonNullable<OrderedListProps['type']>, ListStyleType> = {
  1: 'decimal',
  a: 'lower-alpha',
  A: 'upper-alpha',
  i: 'lower-roman',
  I: 'upper-roman',
};

export const OrderedList = React.forwardRef<HTMLOListElement, OrderedListProps>(
  ({ children, element = 'ORDERED_LIST', marginTop, marginBottom = 'space70', type = '1', ...props }, ref) => {
    return (
      <List
        {...safelySpreadTextProps(props)}
        as="ol"
        element={element}
        marginTop={marginTop}
        marginBottom={marginBottom}
        listStyleType={listStyleMap[type]}
        type={type}
        ref={ref}
      >
        {children}
      </List>
    );
  },
);

Recently we got yet another request, this time to render circles instead of solid discs in nested unordered lists. As you can guess, the blocker here from using Paste's component directly is the decision to hardcode listStyleType="disc" in UnorderedList. I've confirmed that by simply using a raw instance of <List listStyleType={null}> (yes, because List does accept a listStyleType prop, but it's defaulted to "disc" 🙃 ), nested list items will follow the defaults built in to CSS and automatically cycle between disc, circle, etc at various levels of nesting without any intervention.

Now, we could certainly build yet another custom component that is a copy-paste of UnorderedList but with a flexible listStyleType prop, but before we do that I was wondering if we could run this by you folks and see if:

1. There's a better option in both cases?
2. Do you want to crib our implementation for OrderedList? Happy to PR this as well but the process seems pretty involved for a newcomer.
3. Could a similar change be made to UnorderedList, or is that simply too risky due to probably introducing a breaking change to the original issue?
4. This is working as intended and we should either go ahead with a new custom UnorderedList or extending another Paste primitive.

Thanks!

[TwilioPasteBot]

Disclaimer: This is a very experimental bot using OpenAI's GPT-4. The answers may not be correct, a human will review the answer and update it if necessary.

---

Hi there!

It sounds like you've encountered a common challenge when trying to extend the functionality of design system components to meet specific product needs. Your approach to creating a custom OrderedList component that allows for flexible listStyleType props is a clever solution, and it's great to hear you're considering contributing back to the Paste community!

Regarding your questions:

1. Better options for both cases: Based on the information provided in the Paste documentation, your approach to extending the OrderedList and considering a similar extension for UnorderedList seems like a solid path forward. Paste's design philosophy emphasizes controlled styling through props to maintain consistency and accessibility, which means direct customization options are limited. Using the List component as a base for creating more flexible list components, as you've done, aligns with the guidance to use primitives for custom needs.

2. Cribbing your implementation for OrderedList: Your willingness to contribute your solution back to the Paste community is commendable. While I can't speak directly for the Paste team, contributions that enhance flexibility while maintaining the design system's principles are often welcome. The best course of action would be to reach out to the Paste team through their contribution guidelines and discuss the potential for integrating your solution.

3. Changes to UnorderedList: As you've noted, making changes to UnorderedList to introduce a flexible listStyleType prop could be seen as risky, especially if it might affect existing implementations. However, if your solution provides significant value without compromising the design system's integrity, it's worth discussing with the Paste team. They may consider it for future updates or provide guidance on how to best implement your custom component.

4. Working as intended and next steps: The Paste design system is built with specific intentions around customization and consistency. Your approach to extending functionality through custom components based on primitives is in line with Paste's guidance for situations where the existing components don't meet all your needs. Proceeding with your custom UnorderedList or extending another Paste primitive seems like a viable path forward. Additionally, engaging with the Paste community through their GitHub or design system office hours could provide further insights and support.

In summary, your proactive approach to solving these challenges is admirable, and reaching out to the Paste team for discussion and potential contribution could lead to beneficial outcomes for both your team and the broader Paste community.

I also did a search, and I managed to find these other Discussions that might be similar or related to your question. Give them a read to see if they answer your question. If they do, head back here and update this discussion and mark it as answered, pointing others to the related discussion:

• How I can remove list style from UnorderedList? - Answer (updated: 12/01/2022, similarity score: 87%)
• How I can remove list style from UnorderedList? (updated: 12/01/2022, similarity score: 87%)
• UnorderedList list-style css discrepancy compared to Evergreen (updated: 08/02/2023, similarity score: 86%)

[krisantrobus]

Hi @stern-shawn I see from you description you have explored the Lsit component. I would use this for your implementation for nested lists for more control over the symbol styles.

With this component you can set the as prop to ol | ul and we also expose prop listStyleType. I've put a CodeSandbox together here. It doesn't seem to have type safety/ recommendations on the listStyleType value but it is working with no type errors.

Will this work for your use case or is there something this will not provide that the other components would?

[stern-shawn]

Hi Kris, sorry for the delayed response and thanks so much for taking a look into this! Sounds like doing our own implementation of UnorderedList using the List primitive is the approved way to do this, so we'll go ahead and handle it that way for ul like we've done previously for ol/OrderedList. 🙌

Just wanted to make sure I wasn't deviating from the expected use patterns too much, as every bit of customization means we have more things to check whenever we pull in a Paste update 😄

[stern-shawn]

Ah, now I remember why I was a little confused. Trying to just use List directly doesn't actually give us the default CSS experience for nested unordered lists because for some reason the List component defaults listStyleType to disc if none is provided. I must use List AND define listStyleType as null in order to circumvent the default style override that exists there.

So I can either:

1. Use <List ... listStyleType={null} /> as our UnorderedList stand-in
2. Build a custom UnorderedList on top of an also custom impelementation of List itself using the base Text component, without the weird listStyleType = 'disc' override that exists in its props. (Essentially copy-pasting the source for List, with that one edit)

[krisantrobus]

Hey @stern-shawn , sorry for a late followup. I understand the issue now, I've been digging into our old PRs and and saw it was an intentional change in this one #2966. Just checking with the team whether we should remove it our end and have it treated as an un-styled primitive. The alternative would be for us to recommend option a and use that as a stand in for your use case.

[krisantrobus]

Hey @stern-shawn, more background we added this change because of this issue in flex. they are building using the OrderedList and UnorderedList components though so removing default in List shouldn't break anything (it's not even in our docs, hopefully no one uses it).

We decided it's ok to remove it our end and you should be able to pass anything you like to it. The types are messed up because it's inheriting from one of our foundational libs but I've added the link to the list in the JSDoc so you should get it in the tooltip.

Here is a link to the PR. It will get merged soon and be included as part of the next release scheduled for 2025.05.27. We haven't included docs in this as we'd need a new primitives page and may do separate. for usage though, I made 3 Storybook and the source code can be found in the PR but based on your examples it'll work exactly as you're expecting it to.

[nkrantz]

Hey @stern-shawn! Checking back in here - did Kris's suggestions help you figure out a path forward? If there's anything else we can discuss here, let us know, otherwise I'll mark this discussion as answered. Thanks!

[stern-shawn]

Hi! So sorry, I started this and then promptly got pulled into something else 🫠 I'll carve out some time today to go through those options and respond back to Kris!