Solidify component API for className buildup

[levithomason]

We've proven that Semantic UI modules, including animations, can be written with no jQuery. We will officially proceed this way for version 1.

We also need to solidify the component API before continuing. Semantic UI uses html class values for all component properties. We need to choose how we'll build up the className string. This can have great consequence on key areas of the library:

1. Performance
2. Documentation
3. PropTypes Validation
4. Expressiveness
5. Ease of use

Of course, this is also not something we'll be changing once it is settled. Once we narrow these down a bit, I'll do some performance analysis to ensure we make a performant decision.

Here are the proposals so far, please give your thoughts. Keep in mind, this is only the API for className buildup. How we break down components and handle html hierarchy is not part of this issue.

1. Every className is a bool prop

<Dropdown topLeftPointing search selection disabled />
<Button big inverted red compact>Click Me</Button>

• Most expressive
• Best documentation (jsdoc comment on each proptype)
• Best validation (every prop is bool, handle mutually exclusive)
• Might be slowest ?
  • heavy parsing of props to buildup className string (requires props -> className map)
  • very declarative component logic with no parsing required, all props are bool
  • (className build up could be offset by simplified component logic)

2. Use SUI glossary terminology (type, state, variation)

<Dropdown
  type='search selection'
  variation='top left pointing'
  state='disabled'
/>
<Button type='inverted' variation='big red compact'>
  Click Me
</Button>

• Expressive props (but relies on string values)
• OK documentation (harder to document prop string values)
• OK validation (string props are prone to false positives)
• Might be somewhat Slow ?
  • Simple concat for building up className
  • component logic requires parsing props string values (i.e. isActive)

3. Common props as enums, bool for others

<Dropdown pointing='top left' search selection disabled />
<Button size='big' color='red' inverted compact>Click Me</Button>

• Expressive, easy to understand
• Better documentation (bool props are great, harder to document prop string values)
• Better validation (bool props are great, string props tougher to validate)
• Might be slow ?
  • className built from concat + parsing boolean props
  • component logic requires parsing props string values (i.e. isActive)

4. Just use className, as it is in Semantic UI

<Dropdown className='top left pointing search selection disabled'/>
<Button className='big inverted red'>Click Me</Button>

• Least expressive
• Requires alternative documentation
• OK validation (string values tougher to validate)
• Might be fastest ?
  • no parsing nor transforming to buildup className
  • but, component logic requires parsing props string values (i.e. isActive)

4.a Separate SUI classes in ui prop.

<Dropdown ui='top left pointing search selection disabled'/>
<Button ui='big inverted red'>Click Me</Button>

• Improves validation (users classNames can't interfere)
• Improves component logic reliability (user classNames can't interfere)

[levithomason]

Offline consensus says to go with 3 as the most expressive with least parsing required. Also gives best validation actually. Color redd can be caught where as with approach 1, it would be spread as a bool prop.

Also, this expressive and generic API keeps us less coupled to Semantic UI should we want to reuse the component interfaces for other frameworks later.