@workday/canvas-kit-styling 10.0.19 → 10.0.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commonjs/lib/cs.d.ts +63 -26
- package/dist/commonjs/lib/cs.d.ts.map +1 -1
- package/dist/commonjs/lib/cs.js +102 -24
- package/dist/es6/lib/cs.d.ts +63 -26
- package/dist/es6/lib/cs.d.ts.map +1 -1
- package/dist/es6/lib/cs.js +102 -24
- package/package.json +4 -3
|
@@ -147,18 +147,23 @@ export interface CSProps {
|
|
|
147
147
|
* returned by {@link createStyles}, or the result of {@link createVars} and
|
|
148
148
|
* {@link createModifiers}. If you're extending a component already using `cs`, you can merge that
|
|
149
149
|
* prop in as well. Any style that is passed to the `cs` prop will override style props. If you
|
|
150
|
-
* wish to have styles that are overridden by
|
|
151
|
-
*
|
|
150
|
+
* wish to have styles that are overridden by the `css` prop, or styles added via the `styled`
|
|
151
|
+
* API, use {@link handleCsProp} wherever `elemProps` is used. If your component needs to also
|
|
152
|
+
* handle style props, use {@link mergeStyles} instead.
|
|
152
153
|
*
|
|
153
154
|
*
|
|
154
155
|
* ```tsx
|
|
156
|
+
* import {handleCsProp} from '@workday/canvas-kit-styling';
|
|
155
157
|
* import {mergeStyles} from '@workday/canvas-kit-react/layout';
|
|
156
158
|
*
|
|
157
159
|
* // ...
|
|
158
160
|
*
|
|
161
|
+
* // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
|
|
162
|
+
* // function signature, but adds support for style props.
|
|
163
|
+
*
|
|
159
164
|
* return (
|
|
160
165
|
* <Element
|
|
161
|
-
* {...
|
|
166
|
+
* {...handleCsProp(elemProps, [
|
|
162
167
|
* myStyles,
|
|
163
168
|
* myModifiers({ size: 'medium' }),
|
|
164
169
|
* myVars({ backgroundColor: 'red' })
|
|
@@ -199,39 +204,71 @@ export declare function createStyles(...args: ({
|
|
|
199
204
|
styles: string;
|
|
200
205
|
} | StyleProps | string)[]): string;
|
|
201
206
|
/**
|
|
202
|
-
*
|
|
207
|
+
* This function handles the `cs` prop for you, as well as local styles you want to define. It will
|
|
208
|
+
* force style merging with Emotion's runtime APIs, including [styled
|
|
209
|
+
* components](https://emotion.sh/docs/styled) and the [css prop](https://emotion.sh/docs/css-prop).
|
|
210
|
+
*
|
|
211
|
+
* Runtime style merging works by forcing Emotion's styling merging if use of runtime APIs have been
|
|
212
|
+
* detected. If only `createStyles` were used to style a component, the faster non-runtime styling
|
|
213
|
+
* will be used.
|
|
214
|
+
*
|
|
215
|
+
* You can use `handleCsProp` if you wish to use {@link createStyles} on your own components and want
|
|
216
|
+
* your components to be compatible with Emotion's runtime styling APIs.
|
|
203
217
|
*
|
|
204
218
|
* ```tsx
|
|
205
|
-
*
|
|
206
|
-
*
|
|
219
|
+
* import {createStyles, handleCsProp, CSProps} from '@workday/canvas-kit-styling';
|
|
220
|
+
*
|
|
221
|
+
* interface MyComponentProps extends CSProps {
|
|
222
|
+
* // other props
|
|
207
223
|
* }
|
|
208
|
-
* ```
|
|
209
224
|
*
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
225
|
+
* const myStyles = createStyles({
|
|
226
|
+
* background: 'green',
|
|
227
|
+
* height: 40,
|
|
228
|
+
* width: 40
|
|
229
|
+
* })
|
|
213
230
|
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
231
|
+
* const MyComponent = ({children, ...elemProps}: MyComponentProps) => {
|
|
232
|
+
* return (
|
|
233
|
+
* <div
|
|
234
|
+
* {...handleCsProp(elemProps, [myStyles])}
|
|
235
|
+
* >
|
|
236
|
+
* {children}
|
|
237
|
+
* </div>
|
|
238
|
+
* )
|
|
239
|
+
* }
|
|
240
|
+
*
|
|
241
|
+
* const StyledMyComponent(MyComponent)({
|
|
242
|
+
* background: 'red'
|
|
243
|
+
* })
|
|
244
|
+
*
|
|
245
|
+
* const myOverridingStyles = createStyles({
|
|
246
|
+
* background: 'blue'
|
|
218
247
|
* })
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
* style="padding: 10px; --{hash}-background: red;"
|
|
229
|
-
* />
|
|
248
|
+
*
|
|
249
|
+
* // now everything works. Without `handleCsProp`, the last component would be a red box
|
|
250
|
+
* export default () => (
|
|
251
|
+
* <>
|
|
252
|
+
* <MyComponent>Green box</MyComponent>
|
|
253
|
+
* <StyledMyComponent>Red box</StyledMyComponent>
|
|
254
|
+
* <StyledMyComponent cs={myOverridingStyles}>Blue box</StyledMyComponent>
|
|
255
|
+
* </>
|
|
256
|
+
* )
|
|
230
257
|
* ```
|
|
231
258
|
*/
|
|
232
259
|
export declare function handleCsProp<T extends CSProps & {
|
|
233
260
|
className?: string | undefined;
|
|
234
261
|
style?: React.CSSProperties | undefined;
|
|
235
|
-
}>(
|
|
262
|
+
}>(
|
|
263
|
+
/**
|
|
264
|
+
* All the props to be spread onto an element. The `cs` prop will be removed an reduced to
|
|
265
|
+
* `className` and `style` props which should be safe on every element.
|
|
266
|
+
*/
|
|
267
|
+
elemProps: T,
|
|
268
|
+
/**
|
|
269
|
+
* Optional local style created by `createStyles`. Using this parameter, you can style your
|
|
270
|
+
* element while supporting proper style merging order.
|
|
271
|
+
*/
|
|
272
|
+
localCs?: CSToPropsInput): Omit<T, 'cs'>;
|
|
236
273
|
export {};
|
|
237
274
|
//# sourceMappingURL=cs.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cs.d.ts","sourceRoot":"","sources":["../../../lib/cs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"cs.d.ts","sourceRoot":"","sources":["../../../lib/cs.ts"],"names":[],"mappings":"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"}
|
package/dist/commonjs/lib/cs.js
CHANGED
|
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
3
3
|
exports.handleCsProp = exports.createStyles = exports.csToProps = exports.createModifiers = exports.createVars = exports.cssVar = exports.createStylesCache = void 0;
|
|
4
4
|
// eslint-disable-next-line @emotion/no-vanilla
|
|
5
5
|
const css_1 = require("@emotion/css");
|
|
6
|
+
const utils_1 = require("@emotion/utils");
|
|
6
7
|
const serialize_1 = require("@emotion/serialize");
|
|
7
8
|
const uniqueId_1 = require("./uniqueId");
|
|
8
9
|
const slugify_1 = require("./slugify");
|
|
@@ -243,40 +244,117 @@ function createStyles(...args) {
|
|
|
243
244
|
}
|
|
244
245
|
exports.createStyles = createStyles;
|
|
245
246
|
/**
|
|
246
|
-
*
|
|
247
|
+
* This function handles the `cs` prop for you, as well as local styles you want to define. It will
|
|
248
|
+
* force style merging with Emotion's runtime APIs, including [styled
|
|
249
|
+
* components](https://emotion.sh/docs/styled) and the [css prop](https://emotion.sh/docs/css-prop).
|
|
250
|
+
*
|
|
251
|
+
* Runtime style merging works by forcing Emotion's styling merging if use of runtime APIs have been
|
|
252
|
+
* detected. If only `createStyles` were used to style a component, the faster non-runtime styling
|
|
253
|
+
* will be used.
|
|
254
|
+
*
|
|
255
|
+
* You can use `handleCsProp` if you wish to use {@link createStyles} on your own components and want
|
|
256
|
+
* your components to be compatible with Emotion's runtime styling APIs.
|
|
247
257
|
*
|
|
248
258
|
* ```tsx
|
|
249
|
-
*
|
|
250
|
-
*
|
|
259
|
+
* import {createStyles, handleCsProp, CSProps} from '@workday/canvas-kit-styling';
|
|
260
|
+
*
|
|
261
|
+
* interface MyComponentProps extends CSProps {
|
|
262
|
+
* // other props
|
|
251
263
|
* }
|
|
252
|
-
* ```
|
|
253
264
|
*
|
|
254
|
-
*
|
|
255
|
-
*
|
|
256
|
-
*
|
|
265
|
+
* const myStyles = createStyles({
|
|
266
|
+
* background: 'green',
|
|
267
|
+
* height: 40,
|
|
268
|
+
* width: 40
|
|
269
|
+
* })
|
|
257
270
|
*
|
|
258
|
-
*
|
|
259
|
-
*
|
|
260
|
-
*
|
|
261
|
-
*
|
|
271
|
+
* const MyComponent = ({children, ...elemProps}: MyComponentProps) => {
|
|
272
|
+
* return (
|
|
273
|
+
* <div
|
|
274
|
+
* {...handleCsProp(elemProps, [myStyles])}
|
|
275
|
+
* >
|
|
276
|
+
* {children}
|
|
277
|
+
* </div>
|
|
278
|
+
* )
|
|
279
|
+
* }
|
|
280
|
+
*
|
|
281
|
+
* const StyledMyComponent(MyComponent)({
|
|
282
|
+
* background: 'red'
|
|
262
283
|
* })
|
|
263
|
-
* <MyComponent
|
|
264
|
-
* className="foobar"
|
|
265
|
-
* style={{ padding: 10 }}
|
|
266
|
-
* cs={styles}
|
|
267
|
-
* />
|
|
268
284
|
*
|
|
269
|
-
*
|
|
270
|
-
*
|
|
271
|
-
*
|
|
272
|
-
*
|
|
273
|
-
*
|
|
285
|
+
* const myOverridingStyles = createStyles({
|
|
286
|
+
* background: 'blue'
|
|
287
|
+
* })
|
|
288
|
+
*
|
|
289
|
+
* // now everything works. Without `handleCsProp`, the last component would be a red box
|
|
290
|
+
* export default () => (
|
|
291
|
+
* <>
|
|
292
|
+
* <MyComponent>Green box</MyComponent>
|
|
293
|
+
* <StyledMyComponent>Red box</StyledMyComponent>
|
|
294
|
+
* <StyledMyComponent cs={myOverridingStyles}>Blue box</StyledMyComponent>
|
|
295
|
+
* </>
|
|
296
|
+
* )
|
|
274
297
|
* ```
|
|
275
298
|
*/
|
|
276
|
-
function handleCsProp(
|
|
299
|
+
function handleCsProp(
|
|
300
|
+
/**
|
|
301
|
+
* All the props to be spread onto an element. The `cs` prop will be removed an reduced to
|
|
302
|
+
* `className` and `style` props which should be safe on every element.
|
|
303
|
+
*/
|
|
304
|
+
elemProps,
|
|
305
|
+
/**
|
|
306
|
+
* Optional local style created by `createStyles`. Using this parameter, you can style your
|
|
307
|
+
* element while supporting proper style merging order.
|
|
308
|
+
*/
|
|
309
|
+
localCs) {
|
|
310
|
+
const { cs, style, className, ...restProps } = elemProps;
|
|
311
|
+
// We are going to track if any runtime styles are detected
|
|
312
|
+
let shouldRuntimeMergeStyles = false;
|
|
313
|
+
// The order is intentional. The `className` should go first, then the `cs` prop. If we don't do
|
|
314
|
+
// runtime merging, this order doesn't actually matter because the browser doesn't care the order
|
|
315
|
+
// of classes on the element's
|
|
316
|
+
// [classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList). But Emotion
|
|
317
|
+
// _does_ care because it uses the `classList` order to determine style merging. Therefore we
|
|
318
|
+
// should always be careful to order class names knowing we need to support runtime merging if
|
|
319
|
+
// runtime styles are detected.
|
|
320
|
+
const returnProps = csToProps([localCs, className, cs, style]);
|
|
321
|
+
// The following is basically what Emotion does internally to merge styles from different
|
|
322
|
+
// components into a single className. We will do this here for backwards compatibility with
|
|
323
|
+
// runtime style merging. `createStyles` and `@emotion/css` works by creating styles and injecting
|
|
324
|
+
// them immediately into the document. `@emotion/react` and `@emotion/styled` work by injecting
|
|
325
|
+
// styles during the React render cycle. The following links are to source code of
|
|
326
|
+
// `@emotion/styled` and `@emotion/react` respectively that merge styles in a similar manner.
|
|
327
|
+
// - https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/styled/src/base.js#L120C51-L138
|
|
328
|
+
// - https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/react/src/emotion-element.js#L102-L116
|
|
329
|
+
(returnProps.className || '').split(' ').forEach(name => {
|
|
330
|
+
// Here we detect if a className is associated with Emotion's cache. Styles created via
|
|
331
|
+
// `createStyles` do not need special runtime merge treatment, but `@emotion/react` and
|
|
332
|
+
// `@emotion/styled` do. The `createStylesCache` tracks all styles injected into the cache via
|
|
333
|
+
// `createStyles`, so those are filtered out.
|
|
334
|
+
if (!exports.createStylesCache[name] && css_1.cache.registered[name]) {
|
|
335
|
+
shouldRuntimeMergeStyles = true;
|
|
336
|
+
}
|
|
337
|
+
});
|
|
338
|
+
// If runtime styles are detected, we need to do extra work to ensure styles merge according to
|
|
339
|
+
// the rules of Emotion's runtime.
|
|
340
|
+
if (shouldRuntimeMergeStyles) {
|
|
341
|
+
const registeredStyles = [];
|
|
342
|
+
// We are using the raw `css` instead of `createStyles` because `css` uses style hashing and
|
|
343
|
+
// `createStyles` generates a new ID every time. We could use `createStyles` here, but it would
|
|
344
|
+
// be more wasteful and new styles would be generated each React render cycle. `css` is safe to
|
|
345
|
+
// use inside a render function while `createStyles` should always be used outside the React
|
|
346
|
+
// render cycle. The following is `@emotion/utils` and it mutates the passed in
|
|
347
|
+
// `registeredStyles` array. It uses the cache of registered styles and the original className.
|
|
348
|
+
// It returns a string with found registered class names removed.
|
|
349
|
+
returnProps.className = utils_1.getRegisteredStyles(css_1.cache.registered, registeredStyles, returnProps.className || '');
|
|
350
|
+
// The `className` is mutated again, but with a brand new CSS class name of all the merged
|
|
351
|
+
// registered styles. This is how Emotion merges styles from the `css` prop and `styled`
|
|
352
|
+
// components.
|
|
353
|
+
returnProps.className += css_1.css(registeredStyles);
|
|
354
|
+
}
|
|
277
355
|
return {
|
|
278
|
-
...
|
|
279
|
-
...
|
|
356
|
+
...returnProps,
|
|
357
|
+
...restProps,
|
|
280
358
|
};
|
|
281
359
|
}
|
|
282
360
|
exports.handleCsProp = handleCsProp;
|
package/dist/es6/lib/cs.d.ts
CHANGED
|
@@ -147,18 +147,23 @@ export interface CSProps {
|
|
|
147
147
|
* returned by {@link createStyles}, or the result of {@link createVars} and
|
|
148
148
|
* {@link createModifiers}. If you're extending a component already using `cs`, you can merge that
|
|
149
149
|
* prop in as well. Any style that is passed to the `cs` prop will override style props. If you
|
|
150
|
-
* wish to have styles that are overridden by
|
|
151
|
-
*
|
|
150
|
+
* wish to have styles that are overridden by the `css` prop, or styles added via the `styled`
|
|
151
|
+
* API, use {@link handleCsProp} wherever `elemProps` is used. If your component needs to also
|
|
152
|
+
* handle style props, use {@link mergeStyles} instead.
|
|
152
153
|
*
|
|
153
154
|
*
|
|
154
155
|
* ```tsx
|
|
156
|
+
* import {handleCsProp} from '@workday/canvas-kit-styling';
|
|
155
157
|
* import {mergeStyles} from '@workday/canvas-kit-react/layout';
|
|
156
158
|
*
|
|
157
159
|
* // ...
|
|
158
160
|
*
|
|
161
|
+
* // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
|
|
162
|
+
* // function signature, but adds support for style props.
|
|
163
|
+
*
|
|
159
164
|
* return (
|
|
160
165
|
* <Element
|
|
161
|
-
* {...
|
|
166
|
+
* {...handleCsProp(elemProps, [
|
|
162
167
|
* myStyles,
|
|
163
168
|
* myModifiers({ size: 'medium' }),
|
|
164
169
|
* myVars({ backgroundColor: 'red' })
|
|
@@ -199,39 +204,71 @@ export declare function createStyles(...args: ({
|
|
|
199
204
|
styles: string;
|
|
200
205
|
} | StyleProps | string)[]): string;
|
|
201
206
|
/**
|
|
202
|
-
*
|
|
207
|
+
* This function handles the `cs` prop for you, as well as local styles you want to define. It will
|
|
208
|
+
* force style merging with Emotion's runtime APIs, including [styled
|
|
209
|
+
* components](https://emotion.sh/docs/styled) and the [css prop](https://emotion.sh/docs/css-prop).
|
|
210
|
+
*
|
|
211
|
+
* Runtime style merging works by forcing Emotion's styling merging if use of runtime APIs have been
|
|
212
|
+
* detected. If only `createStyles` were used to style a component, the faster non-runtime styling
|
|
213
|
+
* will be used.
|
|
214
|
+
*
|
|
215
|
+
* You can use `handleCsProp` if you wish to use {@link createStyles} on your own components and want
|
|
216
|
+
* your components to be compatible with Emotion's runtime styling APIs.
|
|
203
217
|
*
|
|
204
218
|
* ```tsx
|
|
205
|
-
*
|
|
206
|
-
*
|
|
219
|
+
* import {createStyles, handleCsProp, CSProps} from '@workday/canvas-kit-styling';
|
|
220
|
+
*
|
|
221
|
+
* interface MyComponentProps extends CSProps {
|
|
222
|
+
* // other props
|
|
207
223
|
* }
|
|
208
|
-
* ```
|
|
209
224
|
*
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
225
|
+
* const myStyles = createStyles({
|
|
226
|
+
* background: 'green',
|
|
227
|
+
* height: 40,
|
|
228
|
+
* width: 40
|
|
229
|
+
* })
|
|
213
230
|
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
231
|
+
* const MyComponent = ({children, ...elemProps}: MyComponentProps) => {
|
|
232
|
+
* return (
|
|
233
|
+
* <div
|
|
234
|
+
* {...handleCsProp(elemProps, [myStyles])}
|
|
235
|
+
* >
|
|
236
|
+
* {children}
|
|
237
|
+
* </div>
|
|
238
|
+
* )
|
|
239
|
+
* }
|
|
240
|
+
*
|
|
241
|
+
* const StyledMyComponent(MyComponent)({
|
|
242
|
+
* background: 'red'
|
|
243
|
+
* })
|
|
244
|
+
*
|
|
245
|
+
* const myOverridingStyles = createStyles({
|
|
246
|
+
* background: 'blue'
|
|
218
247
|
* })
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
* style="padding: 10px; --{hash}-background: red;"
|
|
229
|
-
* />
|
|
248
|
+
*
|
|
249
|
+
* // now everything works. Without `handleCsProp`, the last component would be a red box
|
|
250
|
+
* export default () => (
|
|
251
|
+
* <>
|
|
252
|
+
* <MyComponent>Green box</MyComponent>
|
|
253
|
+
* <StyledMyComponent>Red box</StyledMyComponent>
|
|
254
|
+
* <StyledMyComponent cs={myOverridingStyles}>Blue box</StyledMyComponent>
|
|
255
|
+
* </>
|
|
256
|
+
* )
|
|
230
257
|
* ```
|
|
231
258
|
*/
|
|
232
259
|
export declare function handleCsProp<T extends CSProps & {
|
|
233
260
|
className?: string | undefined;
|
|
234
261
|
style?: React.CSSProperties | undefined;
|
|
235
|
-
}>(
|
|
262
|
+
}>(
|
|
263
|
+
/**
|
|
264
|
+
* All the props to be spread onto an element. The `cs` prop will be removed an reduced to
|
|
265
|
+
* `className` and `style` props which should be safe on every element.
|
|
266
|
+
*/
|
|
267
|
+
elemProps: T,
|
|
268
|
+
/**
|
|
269
|
+
* Optional local style created by `createStyles`. Using this parameter, you can style your
|
|
270
|
+
* element while supporting proper style merging order.
|
|
271
|
+
*/
|
|
272
|
+
localCs?: CSToPropsInput): Omit<T, 'cs'>;
|
|
236
273
|
export {};
|
|
237
274
|
//# sourceMappingURL=cs.d.ts.map
|
package/dist/es6/lib/cs.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cs.d.ts","sourceRoot":"","sources":["../../../lib/cs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"cs.d.ts","sourceRoot":"","sources":["../../../lib/cs.ts"],"names":[],"mappings":"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"}
|
package/dist/es6/lib/cs.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
// eslint-disable-next-line @emotion/no-vanilla
|
|
2
2
|
import { cache, css } from '@emotion/css';
|
|
3
|
+
import { getRegisteredStyles } from '@emotion/utils';
|
|
3
4
|
import { serializeStyles } from '@emotion/serialize';
|
|
4
5
|
import { generateUniqueId } from './uniqueId';
|
|
5
6
|
import { slugify } from './slugify';
|
|
@@ -235,39 +236,116 @@ export function createStyles(...args) {
|
|
|
235
236
|
.join(' ');
|
|
236
237
|
}
|
|
237
238
|
/**
|
|
238
|
-
*
|
|
239
|
+
* This function handles the `cs` prop for you, as well as local styles you want to define. It will
|
|
240
|
+
* force style merging with Emotion's runtime APIs, including [styled
|
|
241
|
+
* components](https://emotion.sh/docs/styled) and the [css prop](https://emotion.sh/docs/css-prop).
|
|
242
|
+
*
|
|
243
|
+
* Runtime style merging works by forcing Emotion's styling merging if use of runtime APIs have been
|
|
244
|
+
* detected. If only `createStyles` were used to style a component, the faster non-runtime styling
|
|
245
|
+
* will be used.
|
|
246
|
+
*
|
|
247
|
+
* You can use `handleCsProp` if you wish to use {@link createStyles} on your own components and want
|
|
248
|
+
* your components to be compatible with Emotion's runtime styling APIs.
|
|
239
249
|
*
|
|
240
250
|
* ```tsx
|
|
241
|
-
*
|
|
242
|
-
*
|
|
251
|
+
* import {createStyles, handleCsProp, CSProps} from '@workday/canvas-kit-styling';
|
|
252
|
+
*
|
|
253
|
+
* interface MyComponentProps extends CSProps {
|
|
254
|
+
* // other props
|
|
243
255
|
* }
|
|
244
|
-
* ```
|
|
245
256
|
*
|
|
246
|
-
*
|
|
247
|
-
*
|
|
248
|
-
*
|
|
257
|
+
* const myStyles = createStyles({
|
|
258
|
+
* background: 'green',
|
|
259
|
+
* height: 40,
|
|
260
|
+
* width: 40
|
|
261
|
+
* })
|
|
249
262
|
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
253
|
-
*
|
|
263
|
+
* const MyComponent = ({children, ...elemProps}: MyComponentProps) => {
|
|
264
|
+
* return (
|
|
265
|
+
* <div
|
|
266
|
+
* {...handleCsProp(elemProps, [myStyles])}
|
|
267
|
+
* >
|
|
268
|
+
* {children}
|
|
269
|
+
* </div>
|
|
270
|
+
* )
|
|
271
|
+
* }
|
|
272
|
+
*
|
|
273
|
+
* const StyledMyComponent(MyComponent)({
|
|
274
|
+
* background: 'red'
|
|
254
275
|
* })
|
|
255
|
-
* <MyComponent
|
|
256
|
-
* className="foobar"
|
|
257
|
-
* style={{ padding: 10 }}
|
|
258
|
-
* cs={styles}
|
|
259
|
-
* />
|
|
260
276
|
*
|
|
261
|
-
*
|
|
262
|
-
*
|
|
263
|
-
*
|
|
264
|
-
*
|
|
265
|
-
*
|
|
277
|
+
* const myOverridingStyles = createStyles({
|
|
278
|
+
* background: 'blue'
|
|
279
|
+
* })
|
|
280
|
+
*
|
|
281
|
+
* // now everything works. Without `handleCsProp`, the last component would be a red box
|
|
282
|
+
* export default () => (
|
|
283
|
+
* <>
|
|
284
|
+
* <MyComponent>Green box</MyComponent>
|
|
285
|
+
* <StyledMyComponent>Red box</StyledMyComponent>
|
|
286
|
+
* <StyledMyComponent cs={myOverridingStyles}>Blue box</StyledMyComponent>
|
|
287
|
+
* </>
|
|
288
|
+
* )
|
|
266
289
|
* ```
|
|
267
290
|
*/
|
|
268
|
-
export function handleCsProp(
|
|
291
|
+
export function handleCsProp(
|
|
292
|
+
/**
|
|
293
|
+
* All the props to be spread onto an element. The `cs` prop will be removed an reduced to
|
|
294
|
+
* `className` and `style` props which should be safe on every element.
|
|
295
|
+
*/
|
|
296
|
+
elemProps,
|
|
297
|
+
/**
|
|
298
|
+
* Optional local style created by `createStyles`. Using this parameter, you can style your
|
|
299
|
+
* element while supporting proper style merging order.
|
|
300
|
+
*/
|
|
301
|
+
localCs) {
|
|
302
|
+
const { cs, style, className, ...restProps } = elemProps;
|
|
303
|
+
// We are going to track if any runtime styles are detected
|
|
304
|
+
let shouldRuntimeMergeStyles = false;
|
|
305
|
+
// The order is intentional. The `className` should go first, then the `cs` prop. If we don't do
|
|
306
|
+
// runtime merging, this order doesn't actually matter because the browser doesn't care the order
|
|
307
|
+
// of classes on the element's
|
|
308
|
+
// [classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList). But Emotion
|
|
309
|
+
// _does_ care because it uses the `classList` order to determine style merging. Therefore we
|
|
310
|
+
// should always be careful to order class names knowing we need to support runtime merging if
|
|
311
|
+
// runtime styles are detected.
|
|
312
|
+
const returnProps = csToProps([localCs, className, cs, style]);
|
|
313
|
+
// The following is basically what Emotion does internally to merge styles from different
|
|
314
|
+
// components into a single className. We will do this here for backwards compatibility with
|
|
315
|
+
// runtime style merging. `createStyles` and `@emotion/css` works by creating styles and injecting
|
|
316
|
+
// them immediately into the document. `@emotion/react` and `@emotion/styled` work by injecting
|
|
317
|
+
// styles during the React render cycle. The following links are to source code of
|
|
318
|
+
// `@emotion/styled` and `@emotion/react` respectively that merge styles in a similar manner.
|
|
319
|
+
// - https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/styled/src/base.js#L120C51-L138
|
|
320
|
+
// - https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/react/src/emotion-element.js#L102-L116
|
|
321
|
+
(returnProps.className || '').split(' ').forEach(name => {
|
|
322
|
+
// Here we detect if a className is associated with Emotion's cache. Styles created via
|
|
323
|
+
// `createStyles` do not need special runtime merge treatment, but `@emotion/react` and
|
|
324
|
+
// `@emotion/styled` do. The `createStylesCache` tracks all styles injected into the cache via
|
|
325
|
+
// `createStyles`, so those are filtered out.
|
|
326
|
+
if (!createStylesCache[name] && cache.registered[name]) {
|
|
327
|
+
shouldRuntimeMergeStyles = true;
|
|
328
|
+
}
|
|
329
|
+
});
|
|
330
|
+
// If runtime styles are detected, we need to do extra work to ensure styles merge according to
|
|
331
|
+
// the rules of Emotion's runtime.
|
|
332
|
+
if (shouldRuntimeMergeStyles) {
|
|
333
|
+
const registeredStyles = [];
|
|
334
|
+
// We are using the raw `css` instead of `createStyles` because `css` uses style hashing and
|
|
335
|
+
// `createStyles` generates a new ID every time. We could use `createStyles` here, but it would
|
|
336
|
+
// be more wasteful and new styles would be generated each React render cycle. `css` is safe to
|
|
337
|
+
// use inside a render function while `createStyles` should always be used outside the React
|
|
338
|
+
// render cycle. The following is `@emotion/utils` and it mutates the passed in
|
|
339
|
+
// `registeredStyles` array. It uses the cache of registered styles and the original className.
|
|
340
|
+
// It returns a string with found registered class names removed.
|
|
341
|
+
returnProps.className = getRegisteredStyles(cache.registered, registeredStyles, returnProps.className || '');
|
|
342
|
+
// The `className` is mutated again, but with a brand new CSS class name of all the merged
|
|
343
|
+
// registered styles. This is how Emotion merges styles from the `css` prop and `styled`
|
|
344
|
+
// components.
|
|
345
|
+
returnProps.className += css(registeredStyles);
|
|
346
|
+
}
|
|
269
347
|
return {
|
|
270
|
-
...
|
|
271
|
-
...
|
|
348
|
+
...returnProps,
|
|
349
|
+
...restProps,
|
|
272
350
|
};
|
|
273
351
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workday/canvas-kit-styling",
|
|
3
|
-
"version": "10.0.
|
|
3
|
+
"version": "10.0.21",
|
|
4
4
|
"description": "The custom CSS in JS solution that takes JS styles and turns them into static CSS",
|
|
5
5
|
"author": "Workday, Inc. (https://www.workday.com)",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -53,9 +53,10 @@
|
|
|
53
53
|
"@emotion/react": "^11.7.1",
|
|
54
54
|
"@emotion/serialize": "^1.0.2",
|
|
55
55
|
"@emotion/styled": "^11.6.0",
|
|
56
|
-
"@
|
|
56
|
+
"@emotion/utils": "^1.0.0",
|
|
57
|
+
"@workday/canvas-kit-react": "^10.0.21",
|
|
57
58
|
"@workday/canvas-tokens-web": "^1.0.0",
|
|
58
59
|
"typescript": "4.2"
|
|
59
60
|
},
|
|
60
|
-
"gitHead": "
|
|
61
|
+
"gitHead": "14b620aee6c2726f5950af1948b698556526e9c0"
|
|
61
62
|
}
|