@player-ui/reference-assets-plugin-react 0.0.1-next.1

package/src/assets/input/hooks.tsx

@@ -0,0 +1,277 @@
+import React from 'react';
+import { useBeacon } from '@player-ui/beacon-plugin-react';
+import type { TransformedInput } from '@player-ui/reference-assets-plugin';
+import type { KeyDownHandler } from './types';
+
+export interface InputHookConfig {
+  /** Format the input as the user keys down */
+  liveFormat?: boolean;
+
+  /** Skip sending beacon events for this input */
+  suppressBeacons?: boolean;
+
+  /** Time (ms) to wait before formatting the user input for normal keys */
+  quickFormatDelay?: number;
+
+  /** Time (ms) to wait before formatting the input after the user types a special _slow_ format key */
+  slowFormatDelay?: number;
+
+  /** Keys to use a slower formatter for. Usually reserved for backspace, arrows, tabs, etc */
+  slowFormatKeys?: Array<number | string>;
+
+  /** Symbol to be used for decimal point */
+  decimalSymbol?: string;
+
+  /** Affix to append to value - does not save to model and is only for display on input */
+  prefix?: string;
+
+  /** Affix to prepend to value - does not save to model and is only for display on input */
+  suffix?: string;
+}
+
+const defaultKeyStrings = [
+  'Delete',
+  'Backspace',
+  'Tab',
+  'Home',
+  'End',
+  'ArrowLeft',
+  'ArrowRight',
+  'ArrowUp',
+  'ArrowDown',
+  'Escape',
+];
+
+/** Create a valid config mixing in defaults and user overrides */
+export const getConfig = (
+  userConfig: InputHookConfig = {}
+): Required<InputHookConfig> => {
+  return {
+    liveFormat: true,
+    suppressBeacons: false,
+    quickFormatDelay: 200,
+    slowFormatDelay: 1000,
+    slowFormatKeys: defaultKeyStrings,
+    decimalSymbol: '.',
+    prefix: '',
+    suffix: '',
+    ...userConfig,
+  };
+};
+
+/** A hook to manage beacon changes for input assets */
+export const useInputBeacon = (props: TransformedInput) => {
+  const beaconHandler = useBeacon({ element: 'text_input', asset: props });
+
+  return (newValue: string) => {
+    let action = 'modified';
+
+    if (newValue === props.value) {
+      return;
+    }
+
+    if (newValue && !props.value) {
+      action = 'added';
+    } else if (!newValue && props.value) {
+      action = 'deleted';
+    }
+
+    beaconHandler({ action });
+  };
+};
+
+/**
+ * A hook to manage an input html element as an asset.
+ * The hook returns an object containing props that are expected to reside on any html input.
+ * It will handle formatting, setting values, beaconing, aria-labels, etc.
+ *
+ * @param props - The output of the input transform
+ * @param config - Local config to manage user interaction overrides
+ */
+export const useInputAsset = (
+  props: TransformedInput,
+  config?: InputHookConfig
+) => {
+  const [localValue, setLocalValue] = React.useState(props.value ?? '');
+  const formatTimerRef = React.useRef<NodeJS.Timeout | undefined>(undefined);
+  const inputBeacon = useInputBeacon(props);
+
+  const {
+    liveFormat,
+    suppressBeacons,
+    quickFormatDelay,
+    slowFormatDelay,
+    slowFormatKeys,
+    decimalSymbol,
+    prefix,
+    suffix,
+  } = getConfig(config);
+
+  /** Reset and pending format timers */
+  function clearPending() {
+    if (formatTimerRef.current) {
+      clearTimeout(formatTimerRef.current);
+      formatTimerRef.current = undefined;
+    }
+  }
+
+  /** Determines whether pressed key should trigger slow format or quick format delay */
+  function getFormatDelaySpeed(e: React.KeyboardEvent<HTMLInputElement>) {
+    const key = slowFormatKeys.every((k) => typeof k === 'number')
+      ? e.which
+      : e.key;
+
+    return slowFormatKeys.includes(key) ? slowFormatDelay : quickFormatDelay;
+  }
+
+  /** Affix handling logic on focus */
+  function handleAffixOnFocus(target: HTMLInputElement) {
+    let val = target.value;
+
+    if (suffix) val = val.substring(0, val.indexOf(suffix));
+
+    if (prefix && !val.includes(prefix)) {
+      val = `${prefix}${val}`;
+    }
+
+    return val;
+  }
+
+  /** Edge cases handling for prefix */
+  function handlePrefixEdgeCases(e: React.KeyboardEvent<HTMLInputElement>) {
+    const target = e.target as HTMLInputElement;
+    const start = target.selectionStart;
+    const end = target.selectionEnd;
+    const pl = prefix.length;
+    const atStart = start === pl;
+    const atEnd = end === pl;
+
+    if (start && end && start < pl) {
+      e.preventDefault();
+      target.setSelectionRange(pl, end - start + pl);
+    } else if (
+      (e.key === 'ArrowLeft' && atStart) ||
+      (e.key === 'Backspace' && atStart && atEnd) ||
+      e.key === 'Home'
+    ) {
+      e.preventDefault();
+      target.setSelectionRange(prefix.length, prefix.length);
+    }
+  }
+
+  /** Helper to add affixes to value where appropriate  */
+  function formatValueWithAffix(value: string | undefined) {
+    if (!value) return '';
+
+    return `${prefix}${value}${suffix}`;
+  }
+
+  /** Value handling logic on key down */
+  const onKeyDownHandler: KeyDownHandler = (currentValue: string) => {
+    const symbolPosition = currentValue.indexOf(decimalSymbol);
+    const newValue = props.format(currentValue) ?? '';
+    const newSymbolPosition = newValue.indexOf(decimalSymbol);
+
+    if (
+      (symbolPosition === -1 || symbolPosition === 0) &&
+      newSymbolPosition > 0
+    ) {
+      // formatting added dot, so set cursor before dot
+      return {
+        newValue: newValue.includes(prefix)
+          ? `${newValue}`
+          : `${prefix}${newValue}`,
+        newCursorPosition: newValue.includes(prefix)
+          ? newSymbolPosition
+          : newSymbolPosition + prefix.length,
+      };
+    }
+
+    return {
+      newValue: newValue.includes(prefix)
+        ? `${newValue}`
+        : `${prefix}${newValue}`,
+    };
+  };
+
+  /** On blur, commit the value to the model */
+  const onBlur: React.FocusEventHandler<HTMLInputElement> = (e) => {
+    clearPending();
+
+    const formatted =
+      (prefix
+        ? e.target.value.replace(prefix, '')
+        : props.format(e.target.value)) ?? '';
+
+    if (formatted) {
+      props.set(formatted);
+      setLocalValue(formatValueWithAffix(formatted));
+    } else {
+      props.set('');
+      setLocalValue('');
+    }
+
+    if (!suppressBeacons) {
+      inputBeacon(formatted);
+    }
+  };
+
+  /** Keep track of any user changes */
+  const onChange: React.ChangeEventHandler<HTMLInputElement> = (e) => {
+    setLocalValue(e.target.value);
+  };
+
+  /** Schedule a format of the current input in the future */
+  const onKeyDown: React.KeyboardEventHandler<HTMLInputElement> = (e) => {
+    clearPending();
+
+    if (prefix) handlePrefixEdgeCases(e);
+
+    const target = e.target as HTMLInputElement;
+
+    if (liveFormat) {
+      formatTimerRef.current = setTimeout(() => {
+        const cursorPosition = target.selectionStart;
+        const currentValue = target.value;
+
+        /** Skip formatting if we're in the middle of the input */
+        if (cursorPosition !== currentValue.length) {
+          return;
+        }
+
+        const obj = onKeyDownHandler(currentValue);
+
+        setLocalValue(obj.newValue);
+        target.selectionStart = obj.newCursorPosition ?? target.selectionStart;
+        target.selectionEnd = obj.newCursorPosition ?? target.selectionEnd;
+      }, getFormatDelaySpeed(e));
+    }
+  };
+
+  /** Format value onFocus if affixes exist */
+  const onFocus: React.FocusEventHandler<HTMLInputElement> = (e) => {
+    const target = e.target as HTMLInputElement;
+    const inputEmpty = target.value === '';
+
+    if ((!inputEmpty && suffix) || (inputEmpty && prefix)) {
+      setLocalValue(handleAffixOnFocus(target));
+    }
+  };
+
+  // Update the stored value if data changes
+  const propsValue = props.value;
+  React.useEffect(() => {
+    setLocalValue(formatValueWithAffix(propsValue));
+  }, [propsValue]);
+
+  /** clear anything pending on unmount of input */
+  React.useEffect(() => clearPending, []);
+
+  return {
+    onBlur,
+    onChange,
+    onKeyDown,
+    onFocus,
+    value: localValue,
+  };
+};

package/src/assets/input/index.tsx

@@ -0,0 +1,2 @@
+export * from './Input';
+export * from './hooks';

package/src/assets/input/types.ts

@@ -0,0 +1,6 @@
+import type { TransformedInput } from '@player-ui/reference-assets-plugin';
+
+export type KeyDownHandler = (
+  currentValue: string,
+  props?: TransformedInput
+) => any;

package/src/assets/text/Text.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { Link } from '@chakra-ui/react';
+import type {
+  TextAsset,
+  LinkModifier,
+} from '@player-ui/reference-assets-plugin';
+import { useText } from './hooks';
+
+/** Find any link modifiers on the text */
+export const getLinkModifier = (asset: TextAsset): LinkModifier | undefined => {
+  return asset.modifiers?.find(
+    (mod) =>
+      mod.type === 'link' &&
+      (mod.metaData as LinkModifier['metaData'])?.ref !== undefined
+  ) as LinkModifier;
+};
+
+/** A text asset */
+export const Text = (props: TextAsset) => {
+  const spanProps = useText(props);
+  const linkModifier = getLinkModifier(props);
+  const { value } = props;
+
+  if (linkModifier) {
+    return <Link href={linkModifier.metaData.ref}>{value}</Link>;
+  }
+
+  return <span {...spanProps}>{value}</span>;
+};

package/src/assets/text/hooks.tsx

@@ -0,0 +1,31 @@
+import React, { useContext } from 'react';
+import makeClass from 'clsx';
+import { useAssetProps } from '@player-ui/react-utils';
+import type { TextAsset } from '@player-ui/reference-assets-plugin';
+
+export interface TextModifierContextType {
+  getClassForModifier?<T>(modifier: T): string | undefined;
+}
+
+export const TextModifierContext = React.createContext<
+  TextModifierContextType | undefined
+>(undefined);
+
+/** Get the props for a basic text element */
+export const useText = (props: TextAsset): JSX.IntrinsicElements['span'] => {
+  let className: string | undefined;
+
+  const modifierContext = useContext(TextModifierContext);
+
+  if (props.modifiers && modifierContext?.getClassForModifier) {
+    className = makeClass(
+      ...props.modifiers.map(modifierContext.getClassForModifier)
+    );
+  }
+
+  return {
+    ...useAssetProps(props),
+    className,
+    children: props.value,
+  };
+};

package/src/assets/text/index.tsx

@@ -0,0 +1,2 @@
+export * from './Text';
+export * from './hooks';

package/src/index.tsx

@@ -0,0 +1,2 @@
+export * from './plugin';
+export * from './assets';

package/src/intro.stories.mdx

@@ -0,0 +1,40 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Reference Assets/Intro" />
+
+# Reference Assets
+
+The assets in this section are an example implementation of an Asset Library for Player.
+Each of the Asset components follows the same basic pattern:
+
+| Export                   | Description                                                                                                                                                                                                     |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<Name>Asset`            | Typescript type interface representing the authored player content                                                                                                                                              |
+| `Transformed<Name>Asset` | (optional) - A Typescript interface representing the _transformed_ version of the asset interface. This extends the base interface and includes any state/properties added by the associated transform.         |
+| `transform`              | (optional) - A function (used by the `AssetTransformPlugin`) to adopt Player's current state with the component state. If no `transfrom` is present, the component state is the same as the authored content.   |
+| `Component`              | React component rendering of the given asset. The props are the _transformed_ type (if supplied) or the _authored_ type.                                                                                        |
+
+## Usage
+
+To import and use these Assets in your App, simply import the `plugin` and attach it to Player:
+
+```tsx
+import { useWebPlayer, WebPlayerPlugin } from '@player-ui/react';
+import ReferenceAssetsPlugin from '@player-ui/reference-assets/plugin-react';
+
+const plugins: Array<WebPlayerPlugin> = [new ReferenceAssetsPlugin()];
+
+export const App = () => {
+  // Create Player with our plugins
+  const { webPlayer } = useWebPlayer({ plugins });
+
+  // Start the flow.
+
+  React.useEffect(() => {
+    webPlayer.start(/** Insert your player content */);
+  }, []);
+
+  // Render Player
+  return <webPlayer.Component />;
+};
+```

package/src/plugin.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import type { WebPlayer, WebPlayerPlugin } from '@player-ui/react';
+import type { Player } from '@player-ui/player';
+import { AssetProviderPlugin } from '@player-ui/asset-provider-plugin-react';
+import { ChakraProvider, useTheme } from '@chakra-ui/react';
+import { ReferenceAssetsPlugin as ReferenceAssetsCorePlugin } from '@player-ui/reference-assets-plugin';
+import { Input, Text, Collection, Action, Info } from './assets';
+
+const OptionalChakraThemeProvider = (
+  props: React.PropsWithChildren<unknown>
+) => {
+  const theme = useTheme();
+
+  if (theme) {
+    // eslint-disable-next-line react/jsx-no-useless-fragment
+    return <>{props.children}</>;
+  }
+
+  return <ChakraProvider>{props.children}</ChakraProvider>;
+};
+
+/**
+ * A plugin to register the base reference assets
+ */
+export class ReferenceAssetsPlugin implements WebPlayerPlugin {
+  name = 'reference-assets-web-plugin';
+
+  applyWeb(webplayer: WebPlayer) {
+    webplayer.registerPlugin(
+      new AssetProviderPlugin([
+        ['input', Input],
+        ['text', Text],
+        ['action', Action],
+        ['info', Info],
+        ['collection', Collection],
+      ])
+    );
+
+    webplayer.hooks.webComponent.tap(this.name, (Comp) => {
+      return () => {
+        return (
+          <OptionalChakraThemeProvider>
+            <Comp />
+          </OptionalChakraThemeProvider>
+        );
+      };
+    });
+  }
+
+  apply(player: Player) {
+    player.registerPlugin(new ReferenceAssetsCorePlugin());
+  }
+}