@compiled/react 0.16.1 → 0.16.3

package/dist/esm/xcss-prop/index.d.ts

@@ -1,12 +1,15 @@
 import type * as CSS from 'csstype';
 import type { CSSPseudos, CSSProperties } from '../types';
-type XCSSItem<TStyleDecl extends keyof CSSProperties> = {
-    [Q in keyof CSSProperties]: Q extends TStyleDecl ? CompiledPropertyDeclarationReference | string | number : never;
+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 | (Q extends keyof TCompiledTypedProperty ? TCompiledTypedProperty[Q] : CSSProperties[Q]) : never;
 };
 type XCSSPseudos<TAllowedProperties extends keyof CSSProperties, TAllowedPseudos extends CSSPseudos, TRequiredProperties extends {
     requiredProperties: TAllowedProperties;
-}> = {
-    [Q in CSSPseudos]?: Q extends TAllowedPseudos ? MarkAsRequired<XCSSItem<TAllowedProperties>, TRequiredProperties['requiredProperties']> : never;
+}, TCompiledTypedPseudo> = {
+    [Q in CSSPseudos]?: Q extends TAllowedPseudos ? MarkAsRequired<XCSSItem<TAllowedProperties, Q extends keyof TCompiledTypedPseudo ? TCompiledTypedPseudo[Q] : object>, TRequiredProperties['requiredProperties']> : never;
 };
 /**
  * These APIs we don't want to allow to be passed through the `xcss` prop but we also
@@ -47,7 +50,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:
@@ -106,12 +109,13 @@ export type XCSSAllPseudos = CSSPseudos;
 export type XCSSProp<TAllowedProperties extends keyof CSSProperties, TAllowedPseudos extends CSSPseudos, TRequiredProperties extends {
     requiredProperties: TAllowedProperties;
     requiredPseudos: TAllowedPseudos;
-} = never> = (MarkAsRequired<XCSSItem<TAllowedProperties>, TRequiredProperties['requiredProperties']> & MarkAsRequired<XCSSPseudos<TAllowedProperties, TAllowedPseudos, TRequiredProperties>, TRequiredProperties['requiredPseudos']> & BlockedRules) | false | null | undefined;
-type MarkAsRequired<T, K extends keyof T> = T & {
-    [P in K]-?: T[P];
-};
+} = 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, TCompiledTypedProperty>, TRequiredProperties['requiredProperties']> & MarkAsRequired<XCSSPseudos<TAllowedProperties, TAllowedPseudos, TRequiredProperties, TCompiledTypedPseudo>, TRequiredProperties['requiredPseudos']> & BlockedRules) | false | null | undefined;
 /**
- * ## 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.

package/dist/esm/xcss-prop/index.js

@@ -1,6 +1,6 @@
 import { ac } from '../runtime';
 /**
- * ## 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.

package/dist/esm/xcss-prop/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/xcss-prop/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAiJhC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAChB,GAAG,MAAe,EACD,EAAE;IACnB,2EAA2E;IAC3E,sDAAsD;IACtD,MAAM,YAAY,GAAG,MAA6B,CAAC;IAEnD,+EAA+E;IAC/E,kFAAkF;IAClF,OAAO,EAAE,CAAC,YAAY,CAAoB,CAAC;AAC7C,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/xcss-prop/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAwKhC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAChB,GAAG,MAAe,EACD,EAAE;IACnB,2EAA2E;IAC3E,sDAAsD;IACtD,MAAM,YAAY,GAAG,MAA6B,CAAC;IAEnD,+EAA+E;IAC/E,kFAAkF;IAClF,OAAO,EAAE,CAAC,YAAY,CAAoB,CAAC;AAC7C,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compiled/react",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "A familiar and performant compile time CSS-in-JS library for React.",
   "keywords": [
     "compiled",
@@ -76,6 +76,7 @@
   },
   "devDependencies": {
     "@compiled/benchmark": "^1.1.0",
+    "@fixture/strict-api-test": "*",
     "@testing-library/react": "^12.1.5",
     "@types/jsdom": "^16.2.15",
     "@types/react-dom": "^17.0.22",

package/src/class-names/index.ts

@@ -19,7 +19,7 @@ export interface ClassNamesProps<TProps> {
 }
 
 /**
- * ## Class names
+ * ## Class Names
  *
  * Use a component where styles are not necessarily used on a JSX element.
  * For further details [read the documentation](https://compiledcssinjs.com/docs/api-class-names).

package/src/create-strict-api/__tests__/__fixtures__/strict-api.ts

@@ -0,0 +1,13 @@
+import { createStrictAPI } from '@compiled/react';
+
+const { css, XCSSProp, cssMap, cx } = createStrictAPI<{
+  '&:hover': {
+    color: 'var(--ds-text-hover)';
+    background: 'var(--ds-surface-hover)' | 'var(--ds-surface-sunken-hover)';
+  };
+  color: 'var(--ds-text)';
+  background: 'var(--ds-surface)' | 'var(--ds-surface-sunken)';
+  bkgrnd: 'red' | 'green';
+}>();
+
+export { css, XCSSProp, cssMap, cx };

package/src/create-strict-api/__tests__/index.test.tsx

@@ -0,0 +1,312 @@
+/** @jsxImportSource @compiled/react */
+import { render } from '@testing-library/react';
+
+import { css, cssMap, XCSSProp } from './__fixtures__/strict-api';
+
+describe('createStrictAPI()', () => {
+  describe('css()', () => {
+    it('should type error when circumventing the excess property check', () => {
+      const styles = css({
+        color: 'var(--ds-text)',
+        accentColor: 'red',
+        // @ts-expect-error — Type 'string' is not assignable to type 'undefined'.ts(2322)
+        bkgrnd: 'red',
+        '&:hover': {
+          color: 'var(--ds-text-hover)',
+          // @ts-expect-error — Type 'string' is not assignable to type 'undefined'.ts(2322)
+          bkgrnd: 'red',
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('color', 'var(--ds-text)');
+    });
+
+    it('should constrain declared types for css() func', () => {
+      // @ts-expect-error — Type '"red"' is not assignable to type '"var(--ds-surface)" | "var(--ds-surface-sunken" | undefined'.ts(2322)
+      const styles = css({ background: 'red' });
+
+      const { getByTestId } = render(<div css={styles} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('background-color', 'red');
+    });
+
+    it('should mark all properties as optional', () => {
+      const styles1 = css({});
+      const styles2 = css({ '&:hover': {} });
+
+      const { getByTestId } = render(<div css={[styles1, styles2]} data-testid="div" />);
+
+      expect(getByTestId('div')).not.toHaveCompiledCss('color', 'red');
+    });
+
+    it('should constrain pseudos', () => {
+      const styles = css({
+        // @ts-expect-error — Type '"red"' is not assignable to type '"var(--ds-surface)" | "var(--ds-surface-sunken" | undefined'.ts(2322)
+        background: 'red',
+        '&:hover': {
+          // @ts-expect-error — Type '"red"' is not assignable to type '"var(--ds-surface)" | "var(--ds-surface-sunken" | undefined'.ts(2322)
+          background: 'red',
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('background-color', 'red', { target: ':hover' });
+    });
+
+    it('should allow valid properties inside pseudos that are different to root', () => {
+      const styles = css({
+        background: 'var(--ds-surface)',
+        '&:hover': {
+          accentColor: 'red',
+          background: 'var(--ds-surface-hover)',
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('background', 'var(--ds-surface-hover)', {
+        target: ':hover',
+      });
+    });
+
+    it('should allow valid properties', () => {
+      const styles = css({
+        background: 'var(--ds-surface)',
+        accentColor: 'red',
+        color: 'var(--ds-text)',
+        all: 'inherit',
+        '&:hover': { color: 'var(--ds-text-hover)' },
+        '&:invalid': { color: 'orange' },
+      });
+
+      const { getByTestId } = render(<div css={styles} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('all', 'inherit');
+    });
+  });
+
+  describe('cssMap()', () => {
+    it('should allow valid properties', () => {
+      const styles = cssMap({
+        primary: {
+          background: 'var(--ds-surface)',
+          accentColor: 'red',
+          all: 'inherit',
+          '&:hover': { color: 'var(--ds-text-hover)' },
+          '&:invalid': { color: 'orange' },
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles.primary} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('background', 'var(--ds-surface)');
+    });
+
+    it('should allow valid properties inside pseudos that are different to root', () => {
+      const styles = cssMap({
+        primary: {
+          background: 'var(--ds-surface)',
+          '&:hover': {
+            accentColor: 'red',
+            background: 'var(--ds-surface-hover)',
+          },
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles.primary} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('background', 'var(--ds-surface-hover)', {
+        target: ':hover',
+      });
+    });
+
+    it('should type error invalid vales', () => {
+      const styles = cssMap({
+        primary: {
+          // @ts-expect-error — Type '{ val: string; }' is not assignable to type 'Readonly<Properties<string | number, string & {}>> & PseudosDeclarations & EnforceSchema<{ background: "var(--ds-surface)" | "var(--ds-surface-sunken"; }>'.
+          val: 'ok',
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles.primary} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('val', 'ok');
+    });
+
+    it('should type error invalid values in pseudos', () => {
+      const styles = cssMap({
+        primary: {
+          // @ts-expect-error — Type '"red"' is not assignable to type '"var(--ds-surface)" | "var(--ds-surface-sunken" | undefined'.ts(2322)
+          background: 'red',
+          '&:hover': {
+            // @ts-expect-error — Type 'string' is not assignable to type 'never'.ts(2322)
+            val: 'ok',
+          },
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles.primary} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('val', 'ok', { target: ':hover' });
+    });
+  });
+
+  describe('XCSSProp', () => {
+    it('should allow valid values', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'background', never>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(<Button xcss={{ background: 'var(--ds-surface)' }} />);
+
+      expect(getByTestId('button')).toHaveCompiledCss('background', 'var(--ds-surface)');
+    });
+
+    it('should type error for invalid known values', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'background', never>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(
+        <Button
+          xcss={{
+            // @ts-expect-error — Type '"red"' is not assignable to type '"var(--ds-surface)" | "var(--ds-surface-sunken" | CompiledPropertyDeclarationReference | undefined'.ts(2322)
+            background: 'red',
+            // @ts-expect-error — Type '{ background: string; }' is not assignable to type 'undefined'.ts(2322)
+            '&::after': {
+              background: 'red',
+            },
+          }}
+        />
+      );
+
+      expect(getByTestId('button')).toHaveCompiledCss('background-color', 'red');
+    });
+
+    it('should type error for invalid unknown values', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'background', never>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(
+        <Button
+          xcss={{
+            // @ts-expect-error — Type '{ asd: number; }' is not assignable to type 'Internal$XCSSProp<"background", never, { background: "var(--ds-surface)" | "var(--ds-surface-sunken"; }, PickObjects<{ background: "var(--ds-surface)" | "var(--ds-surface-sunken"; }>, never>'.
+            asd: 0,
+          }}
+        />
+      );
+
+      expect(getByTestId('button')).toHaveCompiledCss('asd', '0');
+    });
+
+    it('should type error for unsupported known pseudos', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'background', never>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+      const { getByTestId } = render(
+        <Button
+          xcss={{
+            // @ts-expect-error — Object literal may only specify known properties, and '':hover'' does not exist in type
+            ':hover': {
+              color: 'red',
+            },
+          }}
+        />
+      );
+
+      expect(getByTestId('button')).toHaveCompiledCss('color', 'red', { target: ':hover' });
+    });
+
+    it('should type error for unsupported unknown pseudos', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'background', never>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(
+        <Button
+          xcss={{
+            // @ts-expect-error — Object literal may only specify known properties, and '':hover'' does not exist in type
+            ':asd': {
+              color: 'red',
+            },
+          }}
+        />
+      );
+
+      expect(getByTestId('button')).toHaveCompiledCss('color', 'red', { target: ':asd' });
+    });
+
+    it('should type error for invalid known values in pseudos', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'color', '&:hover'>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(
+        <Button
+          xcss={{
+            '&:hover': {
+              // @ts-expect-error — Type '"red"' is not assignable to type 'CompiledPropertyDeclarationReference | "var(--ds-text)" | undefined'.ts(2322)
+              color: 'red',
+            },
+          }}
+        />
+      );
+
+      expect(getByTestId('button')).toHaveCompiledCss('color', 'red', { target: ':hover' });
+    });
+
+    it('should type error for invalid unknown values in pseudos', () => {
+      function Button({ xcss }: { xcss: ReturnType<typeof XCSSProp<'color', '&:hover'>> }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(
+        <Button
+          xcss={{
+            '&:hover': {
+              // @ts-expect-error — Type '{ asd: string; }' is not assignable to type 'MarkAsRequired<XCSSItem<"color", { color: "var(--ds-text)"; }>, never>'.
+              asd: 'red',
+            },
+          }}
+        />
+      );
+
+      expect(getByTestId('button')).toHaveCompiledCss('asd', 'red', { target: ':hover' });
+    });
+
+    it('should enforce required properties', () => {
+      function Button({
+        xcss,
+      }: {
+        xcss: ReturnType<
+          typeof XCSSProp<
+            'background',
+            never,
+            { requiredProperties: 'background'; requiredPseudos: never }
+          >
+        >;
+      }) {
+        return <button data-testid="button" className={xcss} />;
+      }
+
+      const { getByTestId } = render(
+        <Button
+          // @ts-expect-error — Type '{}' is not assignable to type 'Internal$XCSSProp<"background", never, EnforceSchema<{ background: "var(--ds-surface)" | "var(--ds-surface-sunken"; }>, object, { requiredProperties: "background"; requiredPseudos: never; }>'.ts(2322)
+          xcss={{}}
+        />
+      );
+
+      expect(getByTestId('button')).not.toHaveCompiledCss('color', 'red');
+    });
+  });
+
+  it('should throw when calling XCSSProp directly', () => {
+    expect(() => {
+      XCSSProp();
+    }).toThrow();
+  });
+});

package/src/create-strict-api/__tests__/package.test.tsx

@@ -0,0 +1,21 @@
+/** @jsxImportSource @compiled/react */
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { css } from '@fixture/strict-api-test';
+import { render } from '@testing-library/react';
+
+describe('createStrictAPI()', () => {
+  describe('css()', () => {
+    it('should type error when circumventing the excess property check', () => {
+      const styles = css({
+        color: 'var(--ds-text)',
+        '&:hover': {
+          color: 'var(--ds-text-hover)',
+        },
+      });
+
+      const { getByTestId } = render(<div css={styles} data-testid="div" />);
+
+      expect(getByTestId('div')).toHaveCompiledCss('color', 'var(--ds-text)');
+    });
+  });
+});

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

@@ -0,0 +1,223 @@
+import type { StrictCSSProperties, CSSPseudos } from '../types';
+import { createSetupError } 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 createSetupError();
+    },
+    cssMap() {
+      throw createSetupError();
+    },
+    cx,
+    XCSSProp() {
+      throw createSetupError();
+    },
+  };
+}

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