make TextButton more visible in styleguide

[ashjtan]

Feature request

Extract the TextButton documentation out of the Button page and give it its own page. (i.e. Alternative 1)

Why?

The 'TextButton' documentation is currently under the 'Button' page in the styleguide because of

• TextButton currently falling under the Button dir
• the auto styleguide generation (generate-api-tables)

making the component difficult to find and the documentation messier.

Alternatives

1. move the TextButton completely out of the Button dir, making it a separate component

i.e. a one-off fix

2. change the formatting of the styleguide to make "subcomponents" more visible

i.e. a more holistic solution

a) use subbullets/dropdowns in the left column to give each subcomponent its own page, rather than putting the documentation for multiple subcomponents in the one page

e.g.
- Button
   - TextButton
- ActionBar
  - ActionBarButton
  - ActionBarLayer
  - InlineActionBar

b) add table-of-contents-like list of hash links to any "subcomponents" at the top of the page

e.g. just above the "Button" title

• this can be done manually in the readme
• one problem with generate-api-tables is that the tables are at the end after all the examples, so with Button and TextButton, it's formatted like

 - Button examples
 - TextButton examples
 - Button props
 - Button slots
 - Button events
 - TextButton props
 - TextButton slots
 - TextButton events

so you can't actually hashlink to the "TextButton" section, since it's all split up. if we change it so that the page is ordered component-by-component rather than examples->tables, this is very feasible.

c) change the UI design of the styleguide to more distinctly split up sections

it's difficult to see a clear distinction between, for example, the Button and TextButton sections. i think it's just the normal markdown formatting. this would need some significant work tho from both the design and eng sides. this is more of an out there idea, not the most feasible one.

Additional context

i'd love to work on this if i got some feedback on the possible solutions.

[landondurnan]

Thanks for submitting the issue and definitely appreciate the consideration of different alternatives. However, I think since the TextButton is technically a separate component we should treat it as such with a separate doc. This keeps our documentation consistent across components and doesn't require any refactoring with the documentation or API tables.

We don't really have a concept of "sub-components", but more so a parent / child definition of components which are all exported as part of the same component.

I could see generating a table of contents valuable at the component level, particularly if we can define standard sections consistently and/or when we are able to generate interactive demos, but for now I think the simplest solution is pulling the markdown demo over to the other component and let it stand on it's own, even if it's very simple.

[ashjtan]

@landondurnan thanks for your feedback and direction! i'll assign this issue to me and get to extracting the TextButton out from Button. it will likely be a breaking change for any TextButton imports, i.e. Import { MTextButton } from '@square/maker/components/Button'; becomes Import { MTextButton } from '@square/maker/components/TextButton';

lmk if you want me to make a new issue for implementing any of the other alternatives (e.g. "table of contents"), where i can copy paste most of this info but remove focus on the TextButton

[landondurnan]

There's likely a larger project with the styleguide changes where a table of contents could be more appropriate. Given the priority of more holistic and interactive documentation right now a separate issue for TOC is likely to sit for a while. We could make a mental note for now and revisit when we're considering all the updates we'd like to make.

[pretzelhammer]

pr merged