@workday/canvas-kit-react 7.0.0-alpha.0-next.6 → 7.0.0-alpha.101-next.26

package/common/lib/utils/models.ts

@@ -92,7 +92,6 @@ export type ToModelConfig<
  *   }
  * })
  */
-
 export const createEventMap = <TEvents extends IEvent>() => <
   TGuardMap extends Record<string, keyof TEvents>,
   TCallbackMap extends Record<string, keyof TEvents>
@@ -209,21 +208,394 @@ export const createEvents = <TEvents extends EventCreator>(events: TEvents) => <
   return {events, eventMap: config as EventMap<ToEvent<TEvents>, TGuardMap, TCallbackMap>};
 };
 
-// const disclosureEvents = createEvents({
-//   show(event: Event | React.SyntheticEvent) {
-//     return {event};
-//   },
-// })({
-//   callbacks: {
-//     onShow: 'show',
-//   },
-//   guards: {
-//     shouldShow: 'show',
-//   },
-// });
-
-// useDisclosureModel({
-//   onShow({data, prevState})
-// });
-
-// <Tabs calbacks={ show: () => {}}
+/**
+ * Special type that will be a placeholder during development. At build time, this generic will be
+ * used to create a real generic type for models. If you use `Generic`, you'll have to create an
+ * explicit type for your configs to preserve the `Generic` symbol, otherwise Typescript will
+ * convert to `any`.
+ */
+export type Generic = any
+
+
+export type ModelExtras<TDefaultConfig, TRequiredConfig, TState, TEvents, TModel> = {
+  /** Default config of the model. Useful when composing models to reused config */
+  defaultConfig: TDefaultConfig;
+  /** Required config of the model. Useful when composing models to reused config */
+  requiredConfig: TRequiredConfig;
+  /**
+   * This is only a type and not a value. If you want to
+   */
+  TConfig: TDefaultConfig & TRequiredConfig;
+  /**
+   * The context of the model. This can be used directly, but is mostly used internally by
+   * `createContainer` or `createSubcomponent` to handle model context automatically.
+   */
+  Context: React.Context<TModel>;
+  /**
+   * This function will separate all elemProps from config props. If a prop is both a config _and_
+   * an elemProp, you can manually apply the prop again.
+   * */
+  getElemProps: <P extends {}>(
+    props: P
+  ) => Omit<
+    P,
+    | keyof TDefaultConfig
+    | keyof TRequiredConfig
+    | keyof ToEventConfig<TState, TEvents>
+  >;
+  /**
+   * A typed function to merge config when composing models together. Guards and Callbacks haven't
+   * been resolved yet. `mergeConfig` is a type-attached function that includes guard and callback
+   * types of the composed model.
+   *
+   *
+   * @example
+   * ```ts
+   * const useComposedModel = createModelHook({
+   *   defaultConfig: useModel.defaultConfig,
+   *   requiredConfig: useModel.requiredConfig,
+   * })(config => {
+   *   const model = useModel(useModel.mergeConfig(config, {
+   *     // runtime will contain config.onUpdateValue, but Typescript can't know about it yet
+   *     // luckily `useModel.mergeConfig` knows about the `onUpdateValue` config option
+   *     onUpdateValue(data, prevState) {
+   *       console.log('onUpdateValue', data, prevState)
+   *     }
+   *   }))
+   *
+   *   return model
+   * })
+   * ```
+   */
+  mergeConfig: (
+    source: TDefaultConfig & TRequiredConfig,
+    target: Partial<
+      TDefaultConfig & TRequiredConfig & ToEventConfig<TState, TEvents>
+    >
+  ) => TDefaultConfig & TRequiredConfig & ToEventConfig<TState, TEvents>;
+};
+
+/**
+ * Generic type for all models. It makes `defaultConfig` have optional keys and adds `getElemProps`
+ * statically to the model function.
+ */
+export type ModelFn<
+  TDefaultConfig,
+  TRequiredConfig,
+  TModel
+> = TModel extends { state: infer TState; events: infer TEvents }
+  ? (<TT_Special_Generic>( // special generic used by post processing to handle generic models
+      config?: Partial<TDefaultConfig> &
+        TRequiredConfig &
+        ToEventConfig<TState, TEvents>
+    ) => TModel ) &
+      ModelExtras<TDefaultConfig, TRequiredConfig, TState, TEvents, TModel>
+  : never;
+
+/**
+ * Generic type that adds guards and callbacks to events. The returned type should be applied to the
+ * return type of a model's config.
+ *
+ * For example,
+ * ```ts
+ * // input
+ * ToEventConfig<State, { updateValue: (data: { val: string }) }>
+ *
+ * //output
+ * {
+ *   shouldUpdateValue(data: {val:string}, state: State): boolean,
+ *   onUpdateValue(data: {val:string}, prevState: State): void
+ * }
+ * ```
+ */
+export type ToEventConfig<TState, TEvents extends Record<string, any>> = {
+  [K in keyof TEvents as `on${Capitalize<string & K>}`]?: (
+    data: Parameters<TEvents[K]>[0],
+    prevState: TState
+  ) => void;
+} & {
+  [K in keyof TEvents as `should${Capitalize<string & K>}`]?: (
+    data: Parameters<TEvents[K]>[0],
+    state: TState
+  ) => boolean;
+};
+
+function capitalize(string: string) {
+  return string[0].toUpperCase() + string.substring(1);
+}
+
+function getGuardName(eventName: string) {
+  return `should${capitalize(eventName)}`;
+}
+
+function getCallbackName(eventName: string) {
+  return `on${capitalize(eventName)}`;
+}
+
+// Merges config together in a way that is type safe and works at runtime with correct rules and order applied
+// to guards and callbacks.
+function mergeConfig<TConfig extends Record<string, any>>(
+  sourceConfig: Partial<TConfig>,
+  newConfig: Partial<TConfig>
+): TConfig {
+  const result = { ...sourceConfig } as TConfig;
+  for (const key in newConfig) {
+    if (
+      typeof newConfig[key] === "function" &&
+      /(on)[A-Z]/.test(key) &&
+      typeof sourceConfig[key] === "function"
+    ) {
+      // merge callbacks and ignore Typescript's errors. We've already tested call signatures
+      //  @ts-ignore
+      result[key] = (data: any, state: any) => {
+        // @ts-ignore
+        sourceConfig[key](data, state);
+        // @ts-ignore
+        newConfig[key](data, state);
+      };
+    } else if (
+      newConfig[key] &&
+      /(should)[A-Z]/.test(key) &&
+      sourceConfig[key]
+    ) {
+      // merge guards and ignore Typescript's errors. We've already tested call signatures
+      // @ts-ignore
+      result[key] = (data: any, state: any) => {
+        // @ts-ignore
+        return sourceConfig[key](data, state) && newConfig[key](data, state);
+      };
+    } else {
+      // @ts-ignore
+      result[key] = newConfig[key]
+    }
+  }
+
+  return result;
+}
+
+export type ExtractModelConfig<T extends (config: any) => any> = T extends (config: infer P) => any ? Required<P> : {}
+
+export type ModelConfig<TDefaultConfig, TRequiredConfig> = {
+  /**
+   * Optional config with any defaults if applicable. The values will both be used
+   * to provide defaults if a config property isn't provided as well as to extract type
+   * information about the config option. To make a default config property really optional,
+   * provide `undefined` as the value and cast as the desired type.
+   *
+   * @example
+   * defaultConfig: {
+   *   // optional config with no default. Your model function will not get a default value
+   *   optional: undefined as undefined | string,
+   *   // defaulted value of inferred type `string`
+   *   defaulted: 'foo',
+   *   // defaulted value with a type override of `'foo' | 'bar'`
+   *   defaultedOverride: 'foo' as 'foo' | 'bar',
+   * }
+   */
+  defaultConfig?: TDefaultConfig;
+  /**
+   * Required config that has no default value. Since this is JavaScript, a value needs to be provided
+   * but the value is ignored at runtime. The value is used only for Typescript inference. You can
+   * use `as` to cast the type to something more specific than the inferred one.
+   *
+   * @example
+   * requiredConfig: {
+   *   // The `1` is ignored at runtime, but the type of `size` is `number`
+   *   size: 1,
+   *   // The value is ignored at runtime, but the type is `'bar' | 'baz'`
+   *   foo: 'bar' as 'bar' | 'baz'
+   * }
+   */
+  requiredConfig?: TRequiredConfig;
+  /**
+   * Use `defaultContext` to set the model passed to components that support rendering without a
+   * model or container component.
+   */
+  defaultContext?: Record<string, any>;
+  /**
+   * Useful if you want to extend a model, but not create a new model context. This allows models to
+   * be compatible with existing compound components. An example might be a modal model extends a
+   * popup model, but uses the same context. If you create your own subcomponents or container
+   * component that utilize this model, you'll need to set this property. Failure to do so will mean
+   * components are not getting the correct context.
+   *
+   * @example
+   * const useMyModel = createModelHook({
+   *   defaultConfig: {
+   *     ...useModel.defaultConfig, // inherit the same default config
+   *     initialValue: '',
+   *   },
+   *   requiredConfig: useModel.requiredConfig, // inherit the same required config
+   *   contextOverride: useModel.Context,
+   * })(config => {
+   *   // config has all the same config `useModel` has, but also `initialValue`
+   *
+   *   const model = useModel(config);
+   *   const [value, setValue] = React.useState(config.initialValue);
+   *   const state = { ...model.state, value } // merge model.state with our state
+   *   const events = {
+   *     ...model.events, // merge model.events with our events
+   *     updateValue(value: string) {
+   *       setValue(value)
+   *     }
+   *   }
+   *
+   *   return {
+   *     ...model, // merge any additional properties added to the model by the `useModel` hook
+   *     state,
+   *     events
+   *   }
+   * })
+   *
+   * const MySubComponent = createSubcomponent('div')({
+   *   modelHook: useMyModel, // this tells the component which model and context to use
+   * })((elemProps, Element, model) => {
+   *   elemProps // { children: React.ReactNode }
+   *   model.state.value // `string`
+   * })
+   */
+  contextOverride?: React.Context<any>
+};
+
+/**
+ * Factory function to create typed models with minimal Typescript required. It is a function that
+ * takes `defaultConfig` and `requiredConfig` and returns a function that will become the definition
+ * of the model. The config objects will be used to generate a `getElemProps` function that is used
+ * to separate model config an element props.
+ *
+ * Typescript will infer all config from the returned `state`, `events`, and the `defaultConfig` and
+ * the `requiredConfig`. `defaultConfig` serves the additional purpose of being a default value if
+ * no config value was provided. `requiredConfig` is a little odd in that config values are ignored
+ * and only used to extract types.
+ *
+ * @example
+ * const useModel = createModelHook({
+ *   defaultConfig: {
+ *     optional: 'right' as 'left' | 'right', // optional type casting
+ *   },
+ *   requiredConfig: {
+ *     size: 1, // values are only used for types and are ignored at runtime
+ *   }
+ * })(config => {
+ *   // config is pre-typed for you based on `defaultConfig`
+ * })
+ */
+export const createModelHook = <TDefaultConfig extends {}, TRequiredConfig extends {}>(
+  options: ModelConfig<TDefaultConfig, TRequiredConfig>
+) => {
+  const { defaultConfig = {}, requiredConfig = {}, defaultContext, contextOverride } =
+    options;
+
+  // create a bunch of refs so we can define the `wrappedModel` function once.
+  const fnRef: { current: any } = { current: null };
+
+  const callbacksRef: { current: string[] } = { current: [] };
+  const guardsRef: { current: string[] } = { current: [] };
+  const Context = contextOverride || React.createContext<any>(defaultContext || {state: {}, events: {}})
+
+  const getElemProps = (props: object) => {
+    // if (eventsRef.current === null) {
+    //   throw Error(
+    //     `useModel.getElemProps() must be called after useModel(). getElemProps needs to determine the events returned by the model to function correctly.\nExample:\nconst model = useModel();\nconst elemProps = useModel.getElemProps(props);`
+    //   );
+    // }
+    const elemProps = {};
+    for (const key in props) {
+      if (
+        !defaultConfig.hasOwnProperty(key) &&
+        !requiredConfig.hasOwnProperty(key) &&
+        !callbacksRef.current.includes(key) &&
+        !guardsRef.current.includes(key)
+      ) {
+        // @ts-ignore  Typescript complains about index signatures and this type is never exposed in definitions, so suppress the error
+        elemProps[key] = props[key];
+      }
+    }
+
+    return elemProps;
+  };
+
+  // we use `any` here because we don't know what the type is here and it is internal. No use
+  // slowing down Typescript to bother type checking
+  function wrappedModelHook(config: Record<string, any>) {
+    const stateRef = React.useRef<Record<string, any>>({})
+    const configRef = React.useRef<Record<string, any>>({})
+    const eventsRef = React.useRef<Record<string, any>>({})
+
+    const { state, events, ...rest } = fnRef.current({
+      ...defaultConfig,
+      ...config,
+    });
+
+    // update all the refs with current values
+    stateRef.current = state;
+    configRef.current = config || {};
+    eventsRef.current = events;
+    if (!callbacksRef.current.length) {
+      callbacksRef.current = (keys(events) as string[]).map(getCallbackName);
+    }
+    if (!guardsRef.current.length) {
+      guardsRef.current = (keys(events) as string[]).map(getGuardName);
+    }
+
+    const wrappedEvents = React.useMemo(() => {
+      return keys(eventsRef.current).reduce((result, key) => {
+        result[key] = (data?: any) => {
+          // Invoke the configured guard if there is one
+          if (!(eventsRef.current[key] as any)._wrapped) {
+            const guardFnName = getGuardName(key);
+
+            if (
+              configRef.current[guardFnName] &&
+              !configRef.current[guardFnName](
+                data,
+                stateRef.current,
+              )
+            ) {
+              return;
+            }
+          }
+
+          // call the event (setter)
+          eventsRef.current[key](data);
+
+          const callbackFnName = getCallbackName(key);
+          if (!(eventsRef.current[key] as any)._wrapped) {
+
+            if (configRef.current[callbackFnName]) {
+              configRef.current[callbackFnName](
+                data,
+                stateRef.current,
+              );
+            }
+          }
+        };
+
+        // Mark this function has been wrapped so we can detect wrapped events and not call guards and callbacks multiple times
+        (result[key] as any)._wrapped = true;
+        return result;
+      }, {} as Record<string, any>);
+    }, []);
+
+    return { state, events: wrappedEvents, ...rest };
+  }
+
+  wrappedModelHook.getElemProps = getElemProps;
+  wrappedModelHook.defaultConfig = defaultConfig;
+  wrappedModelHook.requiredConfig = requiredConfig;
+  wrappedModelHook.mergeConfig = mergeConfig;
+  wrappedModelHook.Context = Context;
+
+  return <
+    TModelFn extends (config: TDefaultConfig & TRequiredConfig) => {
+      state: {};
+      events: Record<string, (...args: any) => void>;
+    }
+  >(
+    fn: TModelFn
+  ): ModelFn<TDefaultConfig, TRequiredConfig, ReturnType<TModelFn>> => {
+    fnRef.current = fn;
+
+    return wrappedModelHook as any; // Typescript complains about the `fn` not matching the signature. It's okay Typescript. It works at runtime
+  };
+};

package/dialog/lib/Dialog.tsx

@@ -1,39 +1,22 @@
 import React from 'react';
 
-import {createComponent, useDefaultModel} from '@workday/canvas-kit-react/common';
-import {
-  Popup,
-  PopupModelContext,
-  PopupModel,
-  PopupModelConfig,
-} from '@workday/canvas-kit-react/popup';
+import {createContainer} from '@workday/canvas-kit-react/common';
+import {Popup} from '@workday/canvas-kit-react/popup';
 
 import {DialogPopper} from './DialogPopper';
 import {DialogCard} from './DialogCard';
 import {useDialogModel} from './hooks';
 
-export interface DialogProps extends PopupModelConfig {
+export interface DialogProps {
   /**
    * The contents of the Dialog. Can be `Dialog` children or any valid elements.
    */
   children: React.ReactNode;
-  /**
-   * A PopupModel. The following behaviors will be automatically applied to this model:
-   * - useInitialFocus
-   * - useReturnFocus
-   * - useCloseOnOutsideClick
-   * - useCloseOnEscape
-   */
-  model?: PopupModel;
 }
 
-export const Dialog = createComponent()({
+export const Dialog = createContainer()({
   displayName: 'Dialog',
-  Component: ({children, model, ...config}: DialogProps) => {
-    const value = useDefaultModel(model, config, useDialogModel);
-
-    return <PopupModelContext.Provider value={value}>{children}</PopupModelContext.Provider>;
-  },
+  modelHook: useDialogModel,
   subComponents: {
     Body: Popup.Body,
     Card: DialogCard,
@@ -43,4 +26,6 @@ export const Dialog = createComponent()({
     Popper: DialogPopper,
     CloseButton: Popup.CloseButton,
   },
+})(({children}: DialogProps) => {
+  return <>{children}</>;
 });

package/dialog/lib/DialogCard.tsx

@@ -1,22 +1,20 @@
 import * as React from 'react';
 
-import {createComponent, useModelContext, ExtractProps} from '@workday/canvas-kit-react/common';
-import {Popup, PopupModelContext} from '@workday/canvas-kit-react/popup';
+import {ExtractProps, createSubcomponent} from '@workday/canvas-kit-react/common';
+import {Popup} from '@workday/canvas-kit-react/popup';
 
-import {useDialogCard} from './hooks';
+import {useDialogCard, useDialogModel} from './hooks';
 
 export interface DialogCardProps extends ExtractProps<typeof Popup.Card, never> {}
 
-export const DialogCard = createComponent('div')({
+export const DialogCard = createSubcomponent('div')({
   displayName: 'Dialog.Card',
-  Component: ({children, model, ...elemProps}: DialogCardProps, ref, Element) => {
-    const localModel = useModelContext(PopupModelContext, model);
-
-    const props = useDialogCard(localModel, elemProps, ref);
-    return (
-      <Popup.Card as={Element} {...props}>
-        {children}
-      </Popup.Card>
-    );
-  },
+  modelHook: useDialogModel,
+  elemPropsHook: useDialogCard,
+})<ExtractProps<typeof Popup.Card, never>>((elemProps, Element, model) => {
+  return (
+    <Popup.Card as={Element} model={model} {...elemProps}>
+      {elemProps.children}
+    </Popup.Card>
+  );
 });

package/dialog/lib/DialogPopper.tsx

@@ -1,27 +1,23 @@
 import * as React from 'react';
 
-import {createComponent, useModelContext, ExtractProps} from '@workday/canvas-kit-react/common';
-import {Popup, PopupModelContext, usePopupPopper, Popper} from '@workday/canvas-kit-react/popup';
+import {createSubcomponent, ExtractProps} from '@workday/canvas-kit-react/common';
+import {Popup, usePopupPopper, Popper} from '@workday/canvas-kit-react/popup';
 
-import {useDialogPopper} from './hooks';
+import {useDialogPopper, useDialogModel} from './hooks';
 
 export interface DialogPopperProps extends ExtractProps<typeof Popup.Popper, never> {}
 
-export const DialogPopper = createComponent('div')({
+export const DialogPopper = createSubcomponent('div')({
   displayName: 'Dialog.Popper',
-  Component: (
-    {children, model, placement, popperOptions, ...elemProps}: DialogPopperProps,
-    ref,
-    Element
-  ) => {
-    const localModel = useModelContext(PopupModelContext, model);
-
-    const popperProps = usePopupPopper(localModel, {placement, popperOptions}, ref);
-    const props = useDialogPopper(localModel, elemProps);
+  modelHook: useDialogModel,
+})<ExtractProps<typeof Popup.Popper, never>>(
+  ({children, placement, popperOptions, ref, ...props}, Element, model) => {
+    const popperProps = usePopupPopper(model, {placement, popperOptions}, ref);
+    const elemProps = useDialogPopper(model, props);
     return (
-      <Element {...props}>
+      <Element {...elemProps}>
         <Popper {...popperProps}>{children}</Popper>
       </Element>
     );
-  },
-});
+  }
+);

package/dialog/lib/hooks/useDialogCard.ts

@@ -1,9 +1,9 @@
-import {composeHooks, createHook} from '@workday/canvas-kit-react/common';
-import {usePopupCard, PopupModel} from '@workday/canvas-kit-react/popup';
+import {composeHooks, createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {usePopupCard, usePopupModel} from '@workday/canvas-kit-react/popup';
 
 export const useDialogCard = composeHooks(
   usePopupCard,
-  createHook(({state}: PopupModel) => {
+  createElemPropsHook(usePopupModel)(({state}) => {
     return {
       id: `dialog-${state.id}`,
     };

package/dialog/lib/hooks/useDialogModel.ts

@@ -1,5 +1,4 @@
 import {
-  PopupModelConfig,
   usePopupModel,
   useInitialFocus,
   useReturnFocus,
@@ -7,8 +6,13 @@ import {
   useCloseOnEscape,
   useFocusRedirect,
 } from '@workday/canvas-kit-react/popup';
+import {createModelHook} from '@workday/canvas-kit-react/common';
 
-export const useDialogModel = (config: PopupModelConfig = {}) => {
+export const useDialogModel = createModelHook({
+  defaultConfig: usePopupModel.defaultConfig,
+  requiredConfig: usePopupModel.requiredConfig,
+  contextOverride: usePopupModel.Context,
+})(config => {
   const model = usePopupModel(config);
 
   useInitialFocus(model);
@@ -18,4 +22,4 @@ export const useDialogModel = (config: PopupModelConfig = {}) => {
   useFocusRedirect(model);
 
   return model;
-};
+});

package/dialog/lib/hooks/useDialogPopper.ts

@@ -1,8 +1,8 @@
-import {createHook} from '@workday/canvas-kit-react/common';
-import {PopupModel} from '@workday/canvas-kit-react/popup';
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {usePopupModel} from '@workday/canvas-kit-react/popup';
 import {CSSProperties} from 'react';
 
-export const useDialogPopper = createHook(({state}: PopupModel) => {
+export const useDialogPopper = createElemPropsHook(usePopupModel)(({state}) => {
   return {
     'aria-owns': `dialog-${state.id}`,
     style: {position: 'absolute'} as CSSProperties, // make sure the element doesn't participate in Flex