Proposed New API
lukemelia opened this issue ยท 7 comments
We have some new ideas for the public API for Freestyle that we think will make conceptual and ergonomic improvements for developers. Here's the idea:
Example of new API usage
The old component names would deprecated. Here is a list:
<FreestyleUsage>
- deprecated, move to Freestyle::Item<FreestyleDynamic>
- deprecated, move to Freestyle::DynamicItem<FreestyleNote>
- deprecated, move to Freestyle::Item'd yielded Note<FreestyleNotes>
- deprecated, was for internal use - open an issue<FreestyleAnnotation>
- deprecated, move to Freestyle::Item'd yielded Note<FreestyleCollection>
- deprecated, move to Freestyle::ItemCollection<FreestyleVariant>
- deprecated, move to Item yielded by ItemCollection<FreestyleGuide>
- deprecated, name change only to Freestyle::Guide<FreestyleMenu>
- deprecated, was for internal use - open an issue<FreestyleUsageControls>
- deprecated, was for internal use - open an issue<FreestylePalette>
- deprecated, name change only to Freestyle::ColorPalette<FreestyleTypeface>
- deprecated, name change only to Freestyle::Typeface<FreestyleSection>
- deprecated, move to Section yielded from Freestyle::Guide<FreestyleSubsection>
- deprecated, was used by yielded Section, still is, internal name change to Freestyle::Subsection<FreestyleSnippet>
- deprecated, was for internal use - open an issue
Alternate idea for achieving goals of Freestyle::DynamicItem, via @mattmcmanus. Basically, Freestyle::Item would have the ability to include a control panel so you wouldn't need a dedicated component:
What @lukemelia mentioned above is a good summary. I have some spikes on this usage pattern that I've been experimenting with in one of our addons. I'm happy to share what I have if that would be helpful.
Here's another riff using Usage
instead of Item
One detail not specifically called out above... this API would see Freestyle get out of the markdown business -- if you want markdown in your notes, you would be responsible for including your own markdown addon and using it in your notes.
Update: this particular change has been completed by #357
Now that a polyfill is available for the Yieldable Named Blocks feature, I thought it would be worth considering how the proposed API would look using that approach:
The biggest advantage I see is that the <Freestyle::Item>
component has control over the order and rendering of each sub-part. There's no need to include a <:source>
like there is in the contextual components version.
FYI: Exploration is continuing in the lc/better-api branch: https://github.com/chrislopresto/ember-freestyle/blob/lc/better-api/doc/API-DESIGN.md #380
Update, the latest releases include <Freestyle::Usage>
, which make some of the ideas in this thread a reality.