@compiled/react 0.16.2 → 0.16.4

package/src/create-strict-api/index.ts

@@ -0,0 +1,223 @@
+import type { StrictCSSProperties, CSSPseudos } from '../types';
+import { createStrictSetupError } from '../utils/error';
+import { type CompiledStyles, cx, type Internal$XCSSProp } from '../xcss-prop';
+
+type PseudosDeclarations = {
+  [Q in CSSPseudos]?: StrictCSSProperties;
+};
+
+type EnforceSchema<TObject> = {
+  [P in keyof TObject]?: P extends keyof CompiledSchema
+    ? TObject[P] extends Record<string, unknown>
+      ? EnforceSchema<TObject[P]>
+      : TObject[P]
+    : never;
+};
+
+type PickObjects<TObject> = {
+  [P in keyof TObject]: TObject[P] extends Record<string, unknown> ? TObject[P] : never;
+};
+
+interface CompiledAPI<TSchema> {
+  /**
+   * ## CSS
+   *
+   * Creates styles that are statically typed and useable with other Compiled APIs.
+   * For further details [read the documentation](https://compiledcssinjs.com/docs/api-css).
+   *
+   * @example
+   * ```
+   * const redText = css({
+   *   color: 'red',
+   * });
+   *
+   * <div css={redText} />
+   * ```
+   */
+  css(
+    styles: StrictCSSProperties & PseudosDeclarations & EnforceSchema<TSchema>
+  ): StrictCSSProperties;
+  /**
+   * ## CSS Map
+   *
+   * Creates a collection of named styles that are statically typed and useable with other Compiled APIs.
+   * For further details [read the documentation](https://compiledcssinjs.com/docs/api-cssmap).
+   *
+   * @example
+   * ```
+   * const styles = cssMap({
+   *  none: { borderStyle: 'none' },
+   *  solid: { borderStyle: 'solid' },
+   * });
+   *
+   * <div css={styles.solid} />
+   * ```
+   */
+  cssMap<
+    TStyles extends Record<
+      string,
+      StrictCSSProperties & PseudosDeclarations & EnforceSchema<TSchema>
+    >
+  >(
+    styles: TStyles
+  ): {
+    readonly [P in keyof TStyles]: CompiledStyles<TStyles[P]>;
+  };
+  /**
+   * ## CX
+   *
+   * Use in conjunction with the {@link XCSSProp} to concatenate and conditionally apply
+   * declared styles. Can only be used with the {@link cssMap} and {@link XCSSProp} APIs.
+   *
+   * @example
+   * ```
+   * const styles = cssMap({
+   *  text: { color: 'var(--ds-text)' },
+   *  primary: { color: 'var(--ds-text-brand)' },
+   * });
+   *
+   * <Component xcss={cx(isPrimary && styles.text, !isPrimary && styles.primary)} />
+   * ```
+   */
+  cx: typeof cx;
+  /**
+   * ## XCSSProp
+   *
+   * Declare styles your component takes with all other styles marked as violations
+   * by the TypeScript compiler. There are two primary use cases for xcss prop:
+   *
+   * - safe style overrides
+   * - inverting style declarations
+   *
+   * Interverting style declarations is interesting for platform teams as
+   * it means products only pay for styles they use as they're now the ones who declare
+   * the styles!
+   *
+   * The {@link XCSSProp} type has generics two of which must be defined — use to explicitly
+   * set want you to maintain as API. Use {@link XCSSAllProperties} and {@link XCSSAllPseudos}
+   * to enable all properties and pseudos.
+   *
+   * The third generic is used to declare what properties and pseudos should be required.
+   *
+   * ```tsx
+   * interface MyComponentProps {
+   *   // Color is accepted, all other properties / pseudos are considered violations.
+   *   xcss?: ReturnType<typeof XCSSProp<'color', never>>;
+   *
+   *   // Only backgrond color and hover pseudo is accepted.
+   *   xcss?: ReturnType<typeof XCSSProp<'backgroundColor', '&:hover'>>;
+   *
+   *   // All properties are accepted, all pseudos are considered violations.
+   *   xcss?: ReturnType<typeof XCSSProp<XCSSAllProperties, never>>;
+   *
+   *   // All properties are accepted, only the hover pseudo is accepted.
+   *   xcss?: ReturnType<typeof XCSSProp<XCSSAllProperties, '&:hover'>>;
+   *
+   *   // The xcss prop is required as well as the color property. No pseudos are required.
+   *   xcss: ReturnType<
+   *    typeof XCSSProp<
+   *      XCSSAllProperties,
+   *      '&:hover',
+   *      { requiredProperties: 'color', requiredPseudos: never }
+   *     >
+   *   >;
+   * }
+   *
+   * function MyComponent({ xcss }: MyComponentProps) {
+   *   return <div css={{ color: 'var(--ds-text-danger)' }} className={xcss} />
+   * }
+   * ```
+   *
+   * The xcss prop works with static inline objects and the [cssMap](https://compiledcssinjs.com/docs/api-cssmap) API.
+   *
+   * ```jsx
+   * // Declared as an inline object
+   * <Component xcss={{ color: 'var(--ds-text)' }} />
+   *
+   * // Declared with the cssMap API
+   * const styles = cssMap({ text: { color: 'var(--ds-text)' } });
+   * <Component xcss={styles.text} />
+   * ```
+   *
+   * To concatenate and conditonally apply styles use the {@link cssMap} and {@link cx} functions.
+   */
+  XCSSProp<
+    TAllowedProperties extends keyof StrictCSSProperties,
+    TAllowedPseudos extends CSSPseudos,
+    TRequiredProperties extends {
+      requiredProperties: TAllowedProperties;
+      requiredPseudos: TAllowedPseudos;
+    } = never
+  >(): Internal$XCSSProp<
+    TAllowedProperties,
+    TAllowedPseudos,
+    TSchema,
+    PickObjects<TSchema>,
+    TRequiredProperties
+  >;
+}
+
+type CompiledSchema = StrictCSSProperties & PseudosDeclarations;
+
+/**
+ * ## Create Strict API
+ *
+ * Returns a strict subset of Compiled APIs augmented by a type definition.
+ * This API does not change Compileds build time behavior — merely augmenting
+ * the returned API types which enforce:
+ *
+ * - all APIs use object types
+ * - property values declared in the type definition must be used (else fallback to defaults)
+ * - a strict subset of pseudo states/selectors
+ * - unknown properties to be a type violation
+ *
+ * To set up:
+ *
+ * 1. Declare the API in a module (either local or in a package):
+ *
+ * @example
+ * ```tsx
+ * // ./foo.ts
+ * const { css } = createStrictAPI<{
+ *   color: 'var(--ds-text)',
+ *   '&:hover': { color: 'var(--ds-text-hover)' }
+ * }>();
+ *
+ * export { css };
+ * ```
+ *
+ * 2. Configure Compiled to pick up this module:
+ *
+ * @example
+ * ```diff
+ * // .compiledcssrc
+ * {
+ * +  "importSources": ["./foo.ts"]
+ * }
+ * ```
+ *
+ * 3. Use the module in your application code:
+ *
+ * @example
+ * ```tsx
+ * import { css } from './foo';
+ *
+ * const styles = css({ color: 'var(--ds-text)' });
+ *
+ * <div css={styles} />
+ * ```
+ */
+export function createStrictAPI<TSchema extends CompiledSchema>(): CompiledAPI<TSchema> {
+  return {
+    css() {
+      throw createStrictSetupError();
+    },
+    cssMap() {
+      throw createStrictSetupError();
+    },
+    cx,
+    XCSSProp() {
+      throw createStrictSetupError();
+    },
+  };
+}

package/src/css/index.ts

@@ -6,7 +6,7 @@ import { createSetupError } from '../utils/error';
 /**
  * ## CSS
  *
- * Define styles that are statically typed and useable with other Compiled APIs.
+ * Create styles that are statically typed and useable with other Compiled APIs.
  * For further details [read the documentation](https://compiledcssinjs.com/docs/api-css).
  *
  * ### Style with objects

package/src/css-map/index.ts

@@ -84,9 +84,9 @@ type ExtendedSelectors = {
 };
 
 /**
- * ## cssMap
+ * ## CSS Map
  *
- * Creates a collection of named CSS rules that are statically typed and useable with other Compiled APIs.
+ * Creates a collection of named styles that are statically typed and useable with other Compiled APIs.
  * For further details [read the documentation](https://compiledcssinjs.com/docs/api-cssmap).
  *
  * @example
@@ -96,9 +96,7 @@ type ExtendedSelectors = {
  *  solid: { borderStyle: 'solid' },
  * });
  *
- * const Component = ({ borderStyle }) => <div css={styles[borderStyle]} />
- *
- * <Component borderStyle="solid" />
+ * <div css={styles.solid} />
  * ```
  */
 export default function cssMap<

package/src/index.ts

@@ -10,6 +10,7 @@ export { styled } from './styled';
 export { ClassNames } from './class-names';
 export { default as css } from './css';
 export { default as cssMap } from './css-map';
+export { createStrictAPI } from './create-strict-api';
 export { type XCSSAllProperties, type XCSSAllPseudos, type XCSSProp, cx } from './xcss-prop';
 
 // Pass through the (classic) jsx runtime.

package/src/types.ts

@@ -95,9 +95,15 @@ export type CSSPseudos =
   | '&:visited';
 
 /**
- * The xcss prop must be given all known available properties even
- * if it takes a subset of them. This is ensure the (lack-of an)
+ * The XCSSProp must be given all known available properties even
+ * if it takes a subset of them. This ensures the (lack-of an)
  * excess property check doesn't enable makers to circumvent the
  * system and pass in values they shouldn't.
  */
 export type CSSProperties = Readonly<CSS.Properties<string | number>>;
+
+/**
+ * A stricter subset of the {@link CSSProperties} type that excludes
+ * vendor and obsolete properties.
+ */
+export type StrictCSSProperties = Readonly<CSS.StandardProperties & CSS.SvgProperties>;

package/src/utils/error.ts

@@ -17,3 +17,23 @@ export const createSetupError = (): Error => {
   Good luck!
 `);
 };
+
+export const createStrictSetupError = (): Error => {
+  return new Error(`
+ ██████╗ ██████╗ ███╗   ███╗██████╗ ██╗██╗     ███████╗██████╗
+██╔════╝██╔═══██╗████╗ ████║██╔══██╗██║██║     ██╔════╝██╔══██╗
+██║     ██║   ██║██╔████╔██║██████╔╝██║██║     █████╗  ██║  ██║
+██║     ██║   ██║██║╚██╔╝██║██╔═══╝ ██║██║     ██╔══╝  ██║  ██║
+╚██████╗╚██████╔╝██║ ╚═╝ ██║██║     ██║███████╗███████╗██████╔╝
+ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝╚══════╝╚══════╝╚═════╝
+
+  @compiled/react
+
+  Code was executed when it shouldn't have. To resolve make sure to:
+
+  1. Set up Compiled.
+  2. Configure importSources in your Compiled config to point to the module that exports the output of createStrictAPI().
+
+  For more information visit https://compiledcssinjs.com/docs/installation and follow the instructions.
+`);
+};

package/src/xcss-prop/index.ts

@@ -3,19 +3,30 @@ import type * as CSS from 'csstype';
 import { ac } from '../runtime';
 import type { CSSPseudos, CSSProperties } from '../types';
 
-type XCSSItem<TStyleDecl extends keyof CSSProperties> = {
+type MarkAsRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+
+type XCSSItem<TStyleDecl extends keyof CSSProperties, TCompiledTypedProperty> = {
   [Q in keyof CSSProperties]: Q extends TStyleDecl
-    ? CompiledPropertyDeclarationReference | string | number
+    ?
+        | CompiledPropertyDeclarationReference
+        | (Q extends keyof TCompiledTypedProperty ? TCompiledTypedProperty[Q] : CSSProperties[Q])
     : never;
 };
 
 type XCSSPseudos<
   TAllowedProperties extends keyof CSSProperties,
   TAllowedPseudos extends CSSPseudos,
-  TRequiredProperties extends { requiredProperties: TAllowedProperties }
+  TRequiredProperties extends { requiredProperties: TAllowedProperties },
+  TCompiledTypedPseudo
 > = {
   [Q in CSSPseudos]?: Q extends TAllowedPseudos
-    ? MarkAsRequired<XCSSItem<TAllowedProperties>, TRequiredProperties['requiredProperties']>
+    ? MarkAsRequired<
+        XCSSItem<
+          TAllowedProperties,
+          Q extends keyof TCompiledTypedPseudo ? TCompiledTypedPseudo[Q] : object
+        >,
+        TRequiredProperties['requiredProperties']
+      >
     : never;
 };
 
@@ -69,7 +80,7 @@ export type XCSSAllProperties = keyof CSSProperties;
 export type XCSSAllPseudos = CSSPseudos;
 
 /**
- * ## xcss prop
+ * ## XCSSProp
  *
  * Declare styles your component takes with all other styles marked as violations
  * by the TypeScript compiler. There are two primary use cases for xcss prop:
@@ -132,10 +143,24 @@ export type XCSSProp<
     requiredProperties: TAllowedProperties;
     requiredPseudos: TAllowedPseudos;
   } = never
+> = Internal$XCSSProp<TAllowedProperties, TAllowedPseudos, object, object, TRequiredProperties>;
+
+export type Internal$XCSSProp<
+  TAllowedProperties extends keyof CSSProperties,
+  TAllowedPseudos extends CSSPseudos,
+  TCompiledTypedProperty,
+  TCompiledTypedPseudo,
+  TRequiredProperties extends {
+    requiredProperties: TAllowedProperties;
+    requiredPseudos: TAllowedPseudos;
+  }
 > =
-  | (MarkAsRequired<XCSSItem<TAllowedProperties>, TRequiredProperties['requiredProperties']> &
+  | (MarkAsRequired<
+      XCSSItem<TAllowedProperties, TCompiledTypedProperty>,
+      TRequiredProperties['requiredProperties']
+    > &
       MarkAsRequired<
-        XCSSPseudos<TAllowedProperties, TAllowedPseudos, TRequiredProperties>,
+        XCSSPseudos<TAllowedProperties, TAllowedPseudos, TRequiredProperties, TCompiledTypedPseudo>,
         TRequiredProperties['requiredPseudos']
       > &
       BlockedRules)
@@ -143,10 +168,8 @@ export type XCSSProp<
   | null
   | undefined;
 
-type MarkAsRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
-
 /**
- * ## cx
+ * ## CX
  *
  * Use in conjunction with the {@link XCSSProp} to concatenate and conditionally apply
  * declared styles. Can only be used with the `cssMap()` and {@link XCSSProp} APIs.