feat: introduce children function to shorthands

[layershifter]

This PR adds support for children callback usage in any existing shorthands. This change was originally made for Stardust UI / Fluent UI Northstar (microsoft/fluent-ui-react#1951) which had the more complicated API.

In case of Semantic UI React this will a soft migration to avoid any breaking changes: new API is added and the previous API becomes deprecated. It's expected to remove the old one with functions in V3.

💡 Motivation for changes

#1724 is discussing to add more types for options in Dropdown, the same issue can be met in Menu. In Fluent UI Northstar these issues were solved with kind prop:

<Menu items={[{ kind: 'divider', key: 'divider' }]} />

However, the current implantation with having shorthand as a function blocks it as there is no way to combine { kind: 'smth' } and () => {} 🤔

🔧 Actual changes

The API was introduced and docs were added, now if you would like to customize rendered elements please use children function on any shorthand:

<Button
  content='Like'
  icon={{
    children: (Component, componentProps) => <Component {...componentProps} color='red' />,
    name: 'question',
  }}
/>

To avoid breaking changes in future releases please modify your existing usages:

<Button
  content='Like'
-  icon={(Component, componentProps) => <Component {...componentProps} />}
+  icon={{ children: (Component, componentProps) => <Component {...componentProps} /> }}
/>

The warning was added to inform users about them.

---

Please share feedback and concerns 👍

[github-actions]

size-limit report

Path	Size
bundle-size/dist/Button.size.js	66.46 KB (+0.11% 🔺)
bundle-size/dist/Icon.size.js	30.65 KB (+0.23% 🔺)
bundle-size/dist/Image.size.js	61.7 KB (+0.12% 🔺)
bundle-size/dist/Modal.size.js	76.72 KB (+0.09% 🔺)
bundle-size/dist/Portal.size.js	47.78 KB (0%)

[codecov-commenter]

Codecov Report

Merging #4029 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #4029   +/-   ##
=======================================
  Coverage   99.84%   99.84%           
=======================================
  Files         183      183           
  Lines        3280     3280           
=======================================
  Hits         3275     3275           
  Misses          5        5           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2d368b9...e1ddd4b. Read the comment docs.

[layershifter]

Released in semantic-ui-react@1.3.0 🚢