docs: (WIP) Style macro docs #9090
Conversation
|
Build successful! 🎉 |
## API Changes
@react-aria/utils/@react-aria/utils:useUpdateEffect useUpdateEffect {
- cb: EffectCallback
+ effect: EffectCallback
dependencies: Array<any>
returnVal: undefined
}@react-spectrum/s2/@react-spectrum/s2:EditableCell EditableCell {
align?: 'start' | 'center' | 'end' = 'start'
children: ReactNode
className?: ClassNameOrFunction<CellRenderProps> = 'react-aria-Cell'
colSpan?: number
id?: Key
isSaving?: boolean
+ onCancel: () => void
onSubmit: () => void
renderEditing: () => ReactNode
showDivider?: boolean
style?: StyleOrFunction<CellRenderProps>
} |
| - The [atomic-css-devtools](https://github.com/astahmer/atomic-css-devtools) extension presents an inspected element's atomic CSS rules | ||
| in a non-atomic format, making it easier to scan. |
There was a problem hiding this comment.
todo: replace with the new devtool extension @snowystinger is making
| This indicates that your `style` macro has a condition that isn't evaluable at build time. This can happen for a variety of reasons such | ||
| as if you've referenced non-constant variables within your `style` macro or if you've called non-macro functions within your `style` macro. | ||
| If you are using Typescript, it can be as simple as forgetting to add `as const` to your own defined reusable macro. |
There was a problem hiding this comment.
Maybe add an example of a macro that would cause this?
| > I tried to pass my `style` macro to `UNSAFE_className` but it doesn't work. | ||
| The `style` macro is not meant to be used with `UNSAFE_className`. Overrides to the Spectrum styles is highly discouraged, | ||
| consider styling an equivalent React Aria Component instead. |
There was a problem hiding this comment.
Already mentioned in the UNSAFE style overrides section but felt it was worth adding here anyways
| <InlineAlert variant="informative"> | ||
| <Heading>Important Note</Heading> | ||
| <Content> | ||
| Due to the atomic nature of the generated CSS rules, it is strongly recommended that you follow the best practices listed [below](#css-optimization). | ||
| Failure to do so can result in large number of duplicate rules and obtuse styling bugs. | ||
| </Content> | ||
| </InlineAlert> |
There was a problem hiding this comment.
Maybe overkill, but it felt like it was important to mention this up front so people realize that this is important
| ## Creating custom components | ||
|
|
||
| In-depth examples are coming soon! | ||
|
|
||
| `mergeStyles` can be used to merge the style strings from multiple macros together, with the latter styles taking precedence similar to object spreading. | ||
| This behavior can be leveraged to create a component API that allows an end user to only override specific styles conditionally. |
There was a problem hiding this comment.
We discussed previously that for this first pass that we want to stick with just modifying this page and create examples of style macros with RAC after the release of the docs. I've opted to keep this section and the once above it for now just to let people know about the existence of mergeStyles/iconStyle/and setting CSS variables with macros, but ideally these would move into an "Advanced" page or something similar to cut down on length here. Will comment on the file as to what I'm thinking the final division should look like
There was a problem hiding this comment.
My imagined ideal end state for these style macro docs is as follows:
This page aka "Styling"
Contains the following top level sections:
- Style macro
- Spectrum components
- Values
- CSS optimization
- CSS Resets
- Developing with style macros
- FAQ
An "Advanced" page, maybe named Styling: Advanced? Or maybe a subpage where it is available in the ToC but not the sidebar?
Contains the following content:
- Conditional styles
- Reusing styles (maybe should be in Styling)?
- Setting CSS variables
- Creating custom components (examples of RAC with style macros. Documentation of
size,space,fontRelative? Or do those belong at the Styling level?)
A Reference page
Contains a listing of every value supported by the style macro. Basically what we have for Colors/etc but including a mapping perhaps for things like spacing/sizing/etc
2 participants
Closes
✅ Pull Request Checklist:
📝 Test Instructions:
🧢 Your Project:
RSP