@workday/canvas-kit-react 6.0.0-beta.0-next.13 → 6.0.0

package/common/lib/theming/breakpoints.ts

@@ -9,43 +9,278 @@ export enum BreakpointKey {
 export type BreakpointFnParam = BreakpointKey | keyof typeof BreakpointKey;
 
 export type CanvasBreakpoints = {
-  zero: number;
-  s: number;
-  m: number;
-  l: number;
-  xl: number;
+  /**
+   * ### Zero Breakpoint
+   *
+   * This breakpoint is useful when you need to set a media query `min-width` below small.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.zero}px)`]: {
+   *     padding: space.xxs,
+   *   },
+   * }
+   * ```
+   */
+  zero: 0;
+  /**
+   * ### Small Breakpoint
+   *
+   * The small breakpoint provides the `min-width` for mobile devices, such as phones and tablets.
+   * This size ranges from a min-width of 320px to a max-width of 767px.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.s}px)`]: {
+   *     padding: space.xs,
+   *   },
+   * }
+   * ```
+   */
+  s: 320;
+  /**
+   * ### Medium Breakpoint
+   *
+   * The medium breakpoint is the min-width for intended for medium screens, such as laptops.
+   * This size ranges from a min-width of 768px to a max-width of 1023px.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.m}px)`]: {
+   *     padding: space.s,
+   *   },
+   * }
+   * ```
+   */
+  m: 768;
+  /**
+   * ### Large Breakpoint
+   *
+   * The large breakpoint is the min-width for intended for large screens, such as desktops.
+   * This size ranges from a min-width of 1024px to a max-width of 1439px.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.m}px)`]: {
+   *     padding: space.s,
+   *   },
+   * }
+   * ```
+   */
+  l: 1024;
+  /**
+   * ### Extra-Large Breakpoint
+   *
+   * The large breakpoint is the min-width for intended for extra-large screens, such as wide monitors and TVs.
+   * This size has a min-width of 1440px and no max-width.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.m}px)`]: {
+   *     padding: space.s
+   *   },
+   * }
+   * ```
+   */
+  xl: 1440;
 };
 
 export const breakpointKeys = ['zero', 's', 'm', 'l', 'xl'] as const;
 
+/**
+ * ### Theme Breakpoint Values
+ *
+ * Breakpoints are used by media queries to conditionally apply or modify styles based on the viewport width.
+ * This allows the UI to be responsive to various screen sizes. This object provides five breakpoint values
+ * that correspond to the min-widths of our standard screen sizes.
+ *
+ * - `zero`: 0
+ * - `s`: 320
+ * - `m`: 768
+ * - `l`: 1024
+ * - `xl`: 1440
+ *
+ * And these are our standard screen size ranges:
+ *
+ * - `small` (320px - 767px) Used for mobile-sized screens
+ * - `medium` (768px - 1023px) Used for tablet-sized screens
+ * - `large` - (1024px - 1439px) Used for laptop and small desktop screens
+ * - `extra-large` (≥1440px) Used for very large screens
+ *
+ * Note: Some applications may only require a subset of screen sizes and not use all breakpoints.
+ *
+ */
 export const breakpoints: CanvasBreakpoints = {
   zero: 0,
-  s: 600,
-  m: 960,
-  l: 1280,
-  xl: 1920,
+  s: 320,
+  m: 768,
+  l: 1024,
+  xl: 1440,
 };
 
 const step = 0.5;
 
+/**
+ * ### Up
+ *
+ * _Returns a media query above the `min-width` for the range of a given breakpoint_
+ *
+ * Given a `start` breakpoint key ("zero", "s", "m", "l", "xl"),
+ * this function returns a media query (string) using a `min-width`.
+ *
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { up } = theme.canvas.breakpoints;
+ * const mediaQuery = up('l'); // Returns '@media (min-width: 1024px)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.m,
+ *   }
+ * };
+ * ```
+ */
 export function up(key: BreakpointFnParam) {
   const value = typeof breakpoints[key as BreakpointKey] === 'number' ? breakpoints[key] : key;
-  return `@media (min-width:${value}px)`;
+  return `@media (min-width: ${value}px)`;
 }
 
-export function down(key: BreakpointFnParam) {
-  const endIndex = breakpointKeys.indexOf(key as BreakpointKey) + 1;
+/**
+ * ### Down
+ *
+ * _Returns a media query below the `max-width` for the range of a given breakpoint_
+ *
+ * Given an `end` breakpoint key ("zero", "s", "m", "l", "xl"),
+ * this function returns a media query (string) using a `max-width`.
+ *
+ * Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.
+ * For example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+ *
+ * If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of `0`,
+ * as seen in the second example below.
+ *
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { down } = theme.canvas.breakpoints;
+ * const mediaQuery = down('m'); // Returns '@media (max-width: 1023.5px)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.m,
+ *   }
+ * };
+ * ```
+ *
+ * This example uses the `xl` breakpoint and only adds a `min-width` of `0` to the media query.
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { down } = theme.canvas.breakpoints;
+ * const mediaQuery = down('xl'); // Returns '@media (min-width: 0)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.m,
+ *   }
+ * };
+ * ```
+ */
+export function down(endKey: BreakpointFnParam) {
+  const endIndex = breakpointKeys.indexOf(endKey as BreakpointKey) + 1;
   const upperbound = breakpoints[breakpointKeys[endIndex]];
-
   if (endIndex === breakpointKeys.length) {
     // xl down applies to all sizes
     return up(BreakpointKey.zero);
   }
 
   const value = typeof upperbound === 'number' && endIndex > 0 ? upperbound : 0;
-  return `@media (max-width:${value - step}px)`;
+  return `@media (max-width: ${value - step}px)`;
 }
 
+/**
+ * ### Between
+ *
+ * _Returns a media query between two given breakpoints_
+ *
+ * Given `start` and `end` breakpoint keys ("zero", "s", "m", "l", "xl"),
+ * this function returns a media query (string) using a min-width and max-width.
+ *
+ * Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.
+ * For example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+ *
+ * If the `xl` breakpoint is provided, this function returns a media query with only a `min-width`,
+ * as seen in the second example below.
+ *
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { between } = theme.canvas.breakpoints;
+ * // Returns '@media (min-width: 320px) and (max-width: 1023.5px)'
+ * const mediaQuery = between('s', 'm');
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.s,
+ *   }
+ * };
+ * ```
+ *
+ * This example uses `xl` as the `end` breakpoint and only adds a min-width to the media query.
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { between } = theme.canvas.breakpoints;
+ * const mediaQuery = between('m', 'xl'); // Returns '@media (min-width: 768px)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.s,
+ *   }
+ * };
+ * ```
+ */
 export function between(start: BreakpointFnParam, end: BreakpointFnParam) {
   const endIndex = breakpointKeys.indexOf(end) + 1;
 
@@ -54,11 +289,56 @@ export function between(start: BreakpointFnParam, end: BreakpointFnParam) {
   }
 
   return (
-    `@media (min-width:${breakpoints[start]}px) and ` +
-    `(max-width:${breakpoints[breakpointKeys[endIndex]] - step}px)`
+    `@media (min-width: ${breakpoints[start]}px) and ` +
+    `(max-width: ${breakpoints[breakpointKeys[endIndex]] - step}px)`
   );
 }
 
+/**
+ * ### Only
+ *
+ * _Returns a media query with a `min-width` and `max-width` for a given breakpoint_
+ *
+ * Given a breakpoint key ("zero", "s", "m", "l", "xl"),
+ * this function returns a media query (string) using a `min-width` and `max-width`.
+ *
+ * Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.
+ * For example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+ *
+ * If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of `1440px`,
+ * as seen in the second example below.
+ *
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { only } = theme.canvas.breakpoints;
+ * const mediaQuery = only('s'); // Returns '@media (min-width: 320px) and (max-width: 767.5px)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.s,
+ *   }
+ * };
+ * ```
+ *
+ * This example uses the `xl` breakpoint and only adds a `min-width` of `1440px` to the media query.
+ * @example
+ * ```ts
+ * import { useTheme } from '@workday/canvas-kit-react/common';
+ * import { space } from '@workday/canvas-kit-react/tokens';
+ *
+ * const theme = useTheme();
+ * const { only } = theme.canvas.breakpoints;
+ * const mediaQuery = only('xl'); // Returns '@media (min-width: 1440px)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.s,
+ *   }
+ * };
+ * ```
+ */
 export function only(key: BreakpointFnParam) {
   return between(key, key);
 }

package/common/lib/theming/types.ts

@@ -36,12 +36,202 @@ export interface CanvasTheme {
     success: CanvasThemePalette;
     neutral: CanvasThemePalette;
   };
+  /**
+   * ### Theme Breakpoints
+   *
+   * Breakpoints are used by media queries to conditionally apply or modify styles based on the viewport width.
+   * This allows the UI to be responsive to various screen sizes.
+   *
+   * This breakpoints object contains `values` and several helper functions: `up`, `down`, `between`, and `only`.
+   * You can find more detailed information by inspecting individual values and functions.
+   */
   breakpoints: {
+    /**
+     * ### Breakpoint Values
+     *
+     * This object provides five breakpoint values
+     * that correspond to the min-widths of our standard screen sizes.
+     *
+     * - `zero`: 0
+     * - `s`: 320
+     * - `m`: 768
+     * - `l`: 1024
+     * - `xl`: 1440
+     *
+     * And these are our standard screen size ranges:
+     *
+     * - `small` (320px - 767px) Used for mobile-sized screens
+     * - `medium` (768px - 1023px) Used for tablet-sized screens
+     * - `large` - (1024px - 1439px) Used for laptop and small desktop screens
+     * - `extra-large` (≥1440px) Used for very large screens
+     *
+     * Note: Some applications may only require a subset of screen sizes and not use all breakpoints.
+     *
+     */
     values: CanvasBreakpoints;
+    /**
+     * ### Up
+     *
+     * _Returns a media query above the `min-width` for the range of a given breakpoint_
+     *
+     * Given a `start` breakpoint key ("zero", "s", "m", "l", "xl"),
+     * this function returns a media query (string) using a `min-width`.
+     *
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { up } = theme.canvas.breakpoints;
+     * const mediaQuery = up('l'); // Returns '@media (min-width: 1024px)'
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.m,
+     *   }
+     * };
+     * ```
+     */
     up: (key: BreakpointFnParam) => string;
+    /**
+     * ### Down
+     *
+     * _Returns a media query below the `max-width` for the range of a given breakpoint_
+     *
+     * Given an `end` breakpoint key ("zero", "s", "m", "l", "xl"),
+     * this function returns a media query (string) using a `max-width`.
+     *
+     * Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.
+     * For example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+     *
+     * If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of `0`,
+     * as seen in the second example below.
+     *
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { down } = theme.canvas.breakpoints;
+     * const mediaQuery = down('m'); // Returns '@media (max-width: 1023.5px)'
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.m,
+     *   }
+     * };
+     * ```
+     *
+     * This example uses the `xl` breakpoint and only adds a `min-width` of `0` to the media query.
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { down } = theme.canvas.breakpoints;
+     * const mediaQuery = down('xl'); // Returns '@media (min-width: 0)'
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.m,
+     *   }
+     * };
+     * ```
+     */
     down: (key: BreakpointFnParam) => string;
-    only: (key: BreakpointFnParam) => string;
+    /**
+     * ### Between
+     *
+     * _Returns a media query between two given breakpoints_
+     *
+     * Given `start` and `end` breakpoint keys ("zero", "s", "m", "l", "xl"),
+     * this function returns a media query (string) using a min-width and max-width.
+     *
+     * Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.
+     * For example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+     *
+     * If the `xl` breakpoint is provided, this function returns a media query with only a `min-width`,
+     * as seen in the second example below.
+     *
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { between } = theme.canvas.breakpoints;
+     * // Returns '@media (min-width: 320px) and (max-width: 1023.5px)'
+     * const mediaQuery = between('s', 'm');
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.s,
+     *   }
+     * };
+     * ```
+     *
+     * This example uses `xl` as the `end` breakpoint and only adds a min-width to the media query.
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { between } = theme.canvas.breakpoints;
+     * const mediaQuery = between('m', 'xl'); // Returns '@media (min-width: 768px)'
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.s,
+     *   }
+     * };
+     * ```
+     */
     between: (start: BreakpointFnParam, end: BreakpointFnParam) => string;
+    /**
+     * ### Only
+     *
+     * _Returns a media query with a `min-width` and `max-width` for a given breakpoint_
+     *
+     * Given a breakpoint key ("zero", "s", "m", "l", "xl"),
+     * this function returns a media query (string) using a `min-width` and `max-width`.
+     *
+     * Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.
+     * For example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+     *
+     * If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of `1440px`,
+     * as seen in the second example below.
+     *
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { only } = theme.canvas.breakpoints;
+     * const mediaQuery = only('s'); // Returns '@media (min-width: 320px) and (max-width: 767.5px)'
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.s,
+     *   }
+     * };
+     * ```
+     *
+     * This example uses the `xl` breakpoint and only adds a `min-width` of `1440px` to the media query.
+     * @example
+     * ```ts
+     * import { useTheme } from '@workday/canvas-kit-react/common';
+     * import { space } from '@workday/canvas-kit-react/tokens';
+     *
+     * const theme = useTheme();
+     * const { only } = theme.canvas.breakpoints;
+     * const mediaQuery = only('xl'); // Returns '@media (min-width: 1440px)'
+     * const styles = {
+     *   [mediaQuery]: {
+     *     padding: space.s,
+     *   }
+     * };
+     * ```
+     */
+    only: (key: BreakpointFnParam) => string;
   };
   direction: ContentDirection;
 }

package/common/lib/utils/components.ts

@@ -132,6 +132,7 @@ export type ElementComponent<T extends React.ElementType, P> = {
   ): JSX.Element;
   (props: PropsWithAs<P, T>): JSX.Element;
   displayName?: string;
+  as<E extends React.ElementType>(as: E): ElementComponent<E, P>;
 };
 
 export type Component<P> = {
@@ -233,6 +234,11 @@ export const createComponent = <
   });
   ReturnedComponent.displayName = displayName;
 
+  // The `any`s are here because `ElementComponent` takes care of the `as` type and the
+  // `ReturnComponent` type is overridden
+  (ReturnedComponent as any).as = (as: any) =>
+    createComponent(as)({displayName, Component, subComponents});
+
   // Cast as `any`. We have already specified the return type. Be careful making changes to this
   // file due to this `any` `ReturnedComponent` is a `React.ForwardRefExoticComponent`, but we want
   // it to be either an `Component` or `ElementComponent`
@@ -278,7 +284,7 @@ export const createHook = <M extends Model<any, any>, PO extends {}, PI extends
 ): BehaviorHook<M, PO> => {
   return (model, elemProps, ref) => {
     const props = mergeProps(fn(model, ref, elemProps || ({} as any)), elemProps || ({} as any));
-    if (!props.hasOwnProperty('ref')) {
+    if (!props.hasOwnProperty('ref') && ref) {
       // This is the weird "incoming ref isn't in props, but outgoing ref is in props" thing
       props.ref = ref;
     }
@@ -286,11 +292,32 @@ export const createHook = <M extends Model<any, any>, PO extends {}, PI extends
   };
 };
 
-export type BehaviorHook<M extends Model<any, any>, O extends {}> = <P extends {}, R>(
-  model: M,
-  elemProps?: P,
-  ref?: React.Ref<R>
-) => O & P & (R extends HTMLOrSVGElement ? {ref: React.Ref<R>} : {});
+export const subModelHook = <M extends Model<any, any>, SM extends Model<any, any>, O extends {}>(
+  fn: (model: M) => SM,
+  hook: BehaviorHook<SM, O>
+): BehaviorHook<M, O> => {
+  return (model: M, props: any, ref: React.Ref<any>) => {
+    return hook(fn(model), props, ref);
+  };
+};
+
+// Typescript function parameters are contravariant while return types are covariant. This is a
+// problem when someone hands us a model that correctly extends `Model<any, any>`, but adds extra
+// properties to the model. So `M extends Model<any, any>`. But the `BehaviorHook` is the return
+// type which will reverse the direction which is no longer true: `Model<any, any> extends M`. In
+// order to avoid this issue, we use the `bivarianceHack` found in ReactJS type definitions. This
+// hack forces Typescript to treat `M` as a bivariant allowing extension to go either direction.
+// Normally this would be less type safe, but we're using a generic `M` as a placeholder so there
+// isn't a real issue. Not 100% this is a bug, but the "hack" is a bit messy.
+// https://www.stephanboyer.com/post/132/what-are-covariance-and-contravariance
+// https://stackoverflow.com/questions/52667959/what-is-the-purpose-of-bivariancehack-in-typescript-types/52668133
+export type BehaviorHook<M extends Model<any, any>, O extends {}> = {
+  bivarianceHack<P extends {}, R>(
+    model: M,
+    elemProps?: P,
+    ref?: React.Ref<R>
+  ): O & P & (R extends HTMLOrSVGElement ? {ref: React.Ref<R>} : {});
+}['bivarianceHack'];
 
 function setRef<T>(ref: React.Ref<T> | undefined, value: T): void {
   if (ref) {
@@ -327,7 +354,7 @@ function setRef<T>(ref: React.Ref<T> | undefined, value: T): void {
  *   return <div ref={elementRef}/>
  * })
  */
-export function useForkRef<T>(ref1?: React.Ref<T>, ref2?: React.Ref<T>): (instance: T) => void {
+export function useForkRef<T>(ref1?: React.Ref<T>, ref2?: React.Ref<T>): React.RefCallback<T> {
   return (value: T) => {
     setRef(ref1, value);
     setRef(ref2, value);
@@ -410,9 +437,9 @@ export function useModelContext<T>(context: React.Context<T>, model?: T): T {
  *   return <div id="foo" {...props}>{children}</div>
  * })
  */
-export function composeHooks<M extends Model<any, any>, O1 extends {}, P extends {}, O2 extends {}>(
-  hook1: (model: M, props: P, ref: React.Ref<any>) => O1,
-  hook2: (model: M, props: P, ref: React.Ref<any>) => O2
+export function composeHooks<M extends Model<any, any>, O1 extends {}, O2 extends {}>(
+  hook1: BehaviorHook<M, O1>,
+  hook2: BehaviorHook<M, O2>
 ): BehaviorHook<M, O1 & O2>;
 
 export function composeHooks<
@@ -423,9 +450,9 @@ export function composeHooks<
   O2 extends {},
   O3 extends {}
 >(
-  hook1: (model: M, props: P, ref: React.Ref<R>) => O1,
-  hook2: (model: M, props: P, ref: React.Ref<R>) => O2,
-  hook3: (model: M, props: P, ref: React.Ref<R>) => O3
+  hook1: BehaviorHook<M, O1>,
+  hook2: BehaviorHook<M, O2>,
+  hook3: BehaviorHook<M, O3>
 ): BehaviorHook<M, O1 & O2 & O3>;
 export function composeHooks<
   M extends Model<any, any>,
@@ -436,10 +463,10 @@ export function composeHooks<
   O3 extends {},
   O4 extends {}
 >(
-  hook1: (model: M, props: P, ref: React.Ref<R>) => O1,
-  hook2: (model: M, props: P, ref: React.Ref<R>) => O2,
-  hook3: (model: M, props: P, ref: React.Ref<R>) => O3,
-  hook4: (model: M, props: P, ref: React.Ref<R>) => O4
+  hook1: BehaviorHook<M, O1>,
+  hook2: BehaviorHook<M, O2>,
+  hook3: BehaviorHook<M, O3>,
+  hook4: BehaviorHook<M, O4>
 ): BehaviorHook<M, O1 & O2 & O3 & O4>;
 export function composeHooks<
   M extends Model<any, any>,
@@ -451,11 +478,11 @@ export function composeHooks<
   O4 extends {},
   O5 extends {}
 >(
-  hook1: (model: M, props: P, ref: React.Ref<R>) => O1,
-  hook2: (model: M, props: P, ref: React.Ref<R>) => O2,
-  hook3: (model: M, props: P, ref: React.Ref<R>) => O3,
-  hook4: (model: M, props: P, ref: React.Ref<R>) => O4,
-  hook5: (model: M, props: P, ref: React.Ref<R>) => O5
+  hook1: BehaviorHook<M, O1>,
+  hook2: BehaviorHook<M, O2>,
+  hook3: BehaviorHook<M, O3>,
+  hook4: BehaviorHook<M, O4>,
+  hook5: BehaviorHook<M, O5>
 ): BehaviorHook<M, O1 & O2 & O3 & O4 & O5>;
 export function composeHooks<M extends Model<any, any>, R, P extends {}, O extends {}>(
   ...hooks: ((model: M, props: P, ref: React.Ref<R>) => O)[]
@@ -465,7 +492,7 @@ export function composeHooks<M extends Model<any, any>, R, P extends {}, O exten
       return hook(model, props, props.ref || ref);
     }, props);
 
-    if (!returnProps.hasOwnProperty('ref')) {
+    if (!returnProps.hasOwnProperty('ref') && ref) {
       // This is the weird "incoming ref isn't in props, but outgoing ref is in props" thing
       returnProps.ref = ref;
     }