Support a "default" key for object in scales

[folz]

The implementation is straightforward, but I wanted to discuss something that I think is a pretty large change to the meaning of get and/or theme paths.

Before this PR, theme-ui does not enforce that get on a theme path will return a primitive value suitable for inclusion in CSS. It assumes either that the theme author will write the theme such that all paths lead to primitive values (that is, avoid using objects or arrays at the end of a path), or that the end programmer will ensure all paths will point to a primitive value (that is, 'red.500', never 'red').

This PR changes the above by moving some of the "ensure path points to a primitive" responsibility to theme-ui, by establishing the convention that path => object ? object.default. This is a special case, though. Why not path => object ? object.500, or path => object ? object.core? Should we support this for object-like values such as Map? What about other ways to store values: path => array ? array['default']? path => symbol ? symbol.description?

theme-ui also allows for sx to contain functions: sx={{color: (theme: Theme) => theme.colors.blue.500}}

This is less ergonomic but more precise than the object.default convention. It's also more typesafe, thanks to the Theme type. What if we allowed the theme to also contain themeGet functions? path => function ? function(theme). This would allow things like

colors: {
  default: themeGet('colors.500'),
  500: 'color500',
  ...
}

Is that a reasonable extension of the "ensure path points to a primitive" responsibility?

Anyway, we don't need to answer literally every question above. Maybe the single special case of object => default is fine here. But I still wanted to bring up the possible implications to have a discussion about.

Closes #936

[jxnblk]

Thanks for tackling this! I think this is a great addition to the API as-is -- it also sets up a nice convention for handling default variants.

What if we allowed the theme to also contain themeGet functions?

I think this is something we'd like to solve for. In the v1 issue, I put this as Idea: Provide some solution for self-referencing scales in other scale definitions. I don't think we need to solve for that in this PR, but feel free to take a stab at proposing what that could look like, if you have time

As far as the ensure path points to a primitive point, that's something I hadn't really considered, but might be good to at least warn users if an object or invalid value is being passed on as CSS.

[jxnblk]

Left a few nits/comments, but nothing blocking -- this looks great, thanks!

[folz]

Thanks for the review! I made the changes you suggested. I'll open a new issue/PR about themeGet functions in themes.

[folz]

Opened an issue to track themeGet reference support here: #961

[jxnblk]

Sweet! Thanks, I think this looks good to go, but want to let it sit for a bit so others have time to review or comment

[hasparus]

This is a really good PR. Why didn't we merge it?
I'll handle the conflicts.

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/systemui/theme-ui/cr5r1fra4
✅ Preview: https://theme-ui-git-folz-default-object.systemui.vercel.app

[hasparus]

@folz, I'm gonna change this to __default to ensure people are using it knowingly. It turned out to be a bit surprising.