@fluentui-react-native/use-tokens 0.1.6

package/src/buildUseTokens.ts

@@ -0,0 +1,89 @@
+import { getMemoCache, GetMemoValue } from '@fluentui-react-native/memo-cache';
+import { immutableMerge } from '@fluentui-react-native/immutable-merge';
+
+/** A function to generate tokens based on a theme */
+export type TokensFromTheme<TTokens, TTheme> = (theme: TTheme) => TTokens;
+
+/**
+ * Types of tokens, can be:
+ * - string - will lookup the name in the theme
+ * - Tokens - will merge the tokens in directly
+ * - Function - will run against the theme once for each unique theme encountered
+ */
+export type TokenSettings<TTokens, TTheme> = string | TTokens | TokensFromTheme<TTokens, TTheme>;
+
+/**
+ * The main signature of a useTokens hook is to take the theme and produce a set of resolved tokens,
+ * as well as a sub-cache, specific to this particular theme, that can be used for caching various styles
+ * or values that are theme specific
+ */
+export type UseTokensCore<TTokens, TTheme> = (theme: TTheme) => [TTokens, GetMemoValue<TTokens>];
+
+/**
+ * The full signature also includes a customize function that returns an updated version of useTokens
+ * that captures both the previous values, and layers in the new values specified
+ */
+export type UseTokens<TTokens, TTheme> = UseTokensCore<TTokens, TTheme> & {
+  customize: (...tokens: TokenSettings<TTokens, TTheme>[]) => UseTokens<TTokens, TTheme>;
+};
+
+/**
+ * Helper function that knows how to try to look up token information from the theme
+ */
+export type GetComponentInfo<TTokens, TTheme> = (theme: TTheme, name: string) => TTokens | TokensFromTheme<TTokens, TTheme>;
+
+/**
+ * Tokens are defined as either:
+ *   TTokens     - an object
+ *   string      - a name to look up in the theme
+ *   function    - a function to run against the theme to produce tokens
+ *
+ * This function maps any of these types into a specific TTokens object.  A string is first lookup up in the theme, returning a function
+ * or object. If the type is a function this will be invoked with the theme to generate the tokens object.
+ *
+ * @param tokenEntry - token entry to start with
+ * @param theme - theme to use for queries
+ * @param getComponentInfo - helper to use to lookup the component in the theme
+ */
+function mapToTokens<TTokens, TTheme>(
+  tokenEntry: TTokens | string | TokensFromTheme<TTokens, TTheme>,
+  theme: TTheme,
+  getComponentInfo: GetComponentInfo<TTokens, TTheme> | undefined,
+): object {
+  if (typeof tokenEntry === 'string') {
+    tokenEntry = (getComponentInfo && (getComponentInfo(theme, tokenEntry) as TTokens)) || ({} as TTokens);
+  }
+  if (typeof tokenEntry === 'function') {
+    tokenEntry = (tokenEntry as TokensFromTheme<TTokens, TTheme>)(theme);
+  }
+  return tokenEntry as unknown as object;
+}
+
+/**
+ * Construct a useStyling hook which returns styled slot props based on props and tokens defined in options and in the theme
+ *
+ * @param options - options which drive behavior for the generated styling hook
+ * @param themeHelper - injected theme functionality
+ */
+export function buildUseTokens<TTokens, TTheme>(
+  getComponentInfo: GetComponentInfo<TTokens, TTheme> | undefined,
+  ...tokens: TokenSettings<TTokens, TTheme>[]
+): UseTokens<TTokens, TTheme> {
+  // create a cache instance for use in this particular call to buildUseTokens
+  const cache = getMemoCache();
+
+  // the core function simply merges layers together, looking up component definitions in the theme as well as executing any
+  // theme functions. This turns the tokens into an array of token objects that then get merged together
+  const useTokensCore = (theme: TTheme) => {
+    // get the base styles all merged together, these will only depend on internal tokens and theme
+    return cache(() => immutableMerge(...tokens.map((value) => mapToTokens(value, theme, getComponentInfo))), [theme]);
+  };
+
+  // attach a customize function to generate a new use
+  useTokensCore.customize = (...newTokens: TokenSettings<TTokens, TTheme>[]) => {
+    const mergedTokens = [...tokens, ...newTokens];
+    return buildUseTokens<TTokens, TTheme>(getComponentInfo, ...mergedTokens);
+  };
+
+  return useTokensCore;
+}

package/src/customizable.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import { TokenSettings, UseTokens } from './buildUseTokens';
+
+/**
+ * A component implementation, with a use tokens hook passed in. Implementing it this way allows the useTokens hook to be
+ * modified by the customization handler
+ */
+export type InjectableComponent<TProps, TTokens, TTheme> = (props: TProps, useTokens: UseTokens<TTokens, TTheme>) => JSX.Element | null;
+
+/**
+ * A component with an attached customize function, used to create alternatively styled versions of the component
+ */
+export type CustomizableComponent<TProps, TTokens, TTheme> = React.FunctionComponent<TProps> & {
+  customize: (...tokens: TokenSettings<TTokens, TTheme>[]) => CustomizableComponent<TProps, TTokens, TTheme>;
+};
+
+/**
+ * Function helper for easily creating a customizable component based on the useTokens hook
+ *
+ * @param injectable - a function component implementation, written in (props, useTokens) => JSX.Element form
+ * @param useTokens - a hook function, generally built via buildUseTokens, used to retrieve design tokens for the component
+ *
+ * @returns - a function component that has a static function called customize attached. Customize will return a
+ *            new component (which can also be customized)
+ */
+export function customizable<TProps, TTokens, TTheme>(
+  injectable: InjectableComponent<TProps, TTokens, TTheme>,
+  useTokens: UseTokens<TTokens, TTheme>,
+): CustomizableComponent<TProps, TTokens, TTheme> {
+  const component = (props: TProps) => injectable(props, useTokens);
+  component.customize = (...tokens: TokenSettings<TTokens, TTheme>[]) => {
+    const useTokensNew = useTokens.customize(...tokens);
+    return customizable(injectable, useTokensNew);
+  };
+  return component;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './applyPropsToTokens';
+export * from './applyTokenLayers';
+export * from './buildUseTokens';
+export * from './customizable';
+export * from './patchTokens';

package/src/patchTokens.test.ts

@@ -0,0 +1,50 @@
+import { patchTokens } from './patchTokens';
+import { getMemoCache } from '@fluentui-react-native/memo-cache';
+
+interface Tokens {
+  uno?: string;
+  dos?: string;
+  tres?: number;
+  quatro?: string | number;
+  cinco?: boolean;
+}
+
+const themeTokens: Tokens = {
+  uno: 'uno',
+  dos: 'dos',
+  tres: 3,
+  quatro: 4,
+  cinco: true,
+};
+
+describe('patchTokens tests', () => {
+  test('props get copied', () => {
+    const cache = getMemoCache();
+    const patchValues = { uno: 'one', quatro: 'quatro' };
+    const [tokens] = patchTokens(themeTokens, cache, patchValues);
+    expect(tokens).not.toBe(themeTokens);
+    for (const key in patchValues) {
+      expect(tokens[key]).toEqual(patchValues[key]);
+    }
+  });
+
+  test('no copied props does not change tokens', () => {
+    const cache = getMemoCache();
+    const patchValues1 = {};
+    const [tokens] = patchTokens(themeTokens, cache, patchValues1);
+    expect(tokens).toBe(themeTokens);
+
+    const patchValues2 = { tres: undefined };
+    const [tokens2] = patchTokens(themeTokens, cache, patchValues2);
+    expect(tokens2).toBe(themeTokens);
+  });
+
+  test('patching tokens cache independent of order', () => {
+    const cache = getMemoCache();
+    const patch1 = { uno: 'one', cinco: false };
+    const patch2 = { cinco: false, uno: 'one' };
+    const [tokens1] = patchTokens(themeTokens, cache, patch1);
+    const [tokens2] = patchTokens(themeTokens, cache, patch2);
+    expect(tokens1).toBe(tokens2);
+  });
+});

package/src/patchTokens.ts

@@ -0,0 +1,30 @@
+import { GetMemoValue } from '@fluentui-react-native/memo-cache';
+
+/**
+ * Take a set of tokens (and a memo-cache) and apply changes to those tokens from an additional set of tokens. Only keys which are
+ * not undefined will be applied and if no changes are detected the token object will be unchanged.
+ *
+ * @param tokens - base set of tokens to apply changes to, this will not be modified
+ * @param cache - cache corresponding to this set of tokens
+ * @param patchValues - new values to apply, values will be obtained via keys in the object
+ * @returns - a tuple consisting of a new tokens object and a new memo-cache
+ */
+export function patchTokens<TTokens>(
+  tokens: TTokens,
+  cache: GetMemoValue<TTokens>,
+  patchValues: TTokens,
+): [TTokens, GetMemoValue<TTokens>] {
+  // reduce the patch values to the set of keys that are defined, and sort them to ensure consistent ordering
+  const keys = Object.keys(patchValues)
+    .filter((v) => patchValues[v] !== undefined)
+    .sort();
+
+  // for each key get an updated tokens collection based on key + value. Value alone isn't sufficient as the values
+  // are not necessarily unique. i.e. { a: 'blue' } and { b: 'blue' } would cache to the same without the key
+  for (const key of keys) {
+    [tokens, cache] = cache(() => ({ ...tokens, [key]: patchValues[key] }), [key, patchValues[key]]);
+  }
+
+  // return the updated tokens and cache (if there were any keys applied)
+  return [tokens, cache];
+}

package/src/useTokens.samples.test.tsx

@@ -0,0 +1,219 @@
+import { TextProps, Text, View } from 'react-native';
+import toJson from 'enzyme-to-json';
+import * as React from 'react';
+import { mount } from 'enzyme';
+import { buildUseTokens } from './buildUseTokens';
+import { mergeStyles } from '@fluentui-react-native/merge-props';
+import { immutableMerge } from '@fluentui-react-native/immutable-merge';
+
+/**
+ * Sample super simple theming implementation, shared by all the samples. This is intended to be illustrative,
+ * not to be production ready theming code
+ */
+
+/**
+ * The theme just contains global values and options for looking up component overrides
+ */
+type Theme = {
+  globals: {
+    backgroundColor: string;
+    color: string;
+    borderColor: string;
+    fontFamily: string;
+    fontSize: number;
+  };
+  components: {
+    [key: string]: any;
+  };
+};
+
+/**
+ * The default/base theme just contains base values
+ */
+const baseTheme: Theme = {
+  globals: {
+    backgroundColor: 'white',
+    color: 'black',
+    borderColor: 'blue',
+    fontFamily: 'Arial',
+    fontSize: 12,
+  },
+  components: {},
+};
+
+const current = { theme: baseTheme };
+
+const useTheme = () => current.theme;
+
+const setActiveTheme = (theme?: Partial<Theme>) => {
+  current.theme = (theme && immutableMerge<Theme>(baseTheme, theme as Theme)) || baseTheme;
+};
+
+/**
+ * this wrapper solves the (so-far) inexplicable type errors from the matchers in typescript
+ */
+function snapshotTestTree(tree: any) {
+  (expect(toJson(tree)) as any).toMatchSnapshot();
+}
+
+/**
+ * Helper function used to look up a component in the theme. Having this injected allows this module to not be dependent on the shape of
+ * the theme used.
+ */
+const getComponentInfo = (theme: Theme, name: string) => theme.components[name];
+
+describe('useTokens samples', () => {
+  /**
+   * Sample #1 - Themeable text element
+   *
+   * This adds some default opinions for how a text element should be styled but only allows for customization
+   * via theming
+   */
+
+  // the tokens for customization are just the color and font props from the theme
+  type Sample1Tokens = {
+    color?: string;
+    fontFamily?: string;
+    fontSize?: number;
+  };
+
+  const useTokensSample1 = buildUseTokens<Sample1Tokens, Theme>(
+    getComponentInfo,
+    /** first the default values should come from the global theme section */
+    (t: Theme) => ({
+      color: t.globals.color,
+      fontFamily: t.globals.fontFamily,
+      fontSize: t.globals.fontSize,
+    }),
+    /** next we should look for a component reference to overlay */
+    'SampleText',
+  );
+
+  const SampleText1: React.FunctionComponent<TextProps> = (props) => {
+    // standard props splitting
+    const { style, children, ...rest } = props;
+
+    // typically this would start with a call to retrieve the theme from the context via whatever method is appropriate
+    const theme = useTheme();
+
+    // next the tokens are resolved from the theme, a cache specific to this theme is returned as well to allow for
+    // style objects to not be rebuilt unnecessarily
+    const [tokens, cache] = useTokensSample1(theme);
+
+    // build up the text style, or the full props as appropriate
+    const styleFromTokens = cache(
+      /**
+       * first build the style object
+       * - this executes once for every unique set of keys.
+       * - The cache is already unique for this theme
+       */
+      () => ({ ...tokens }),
+      /**
+       * now specify the keys
+       * - because the only changing variable is the theme
+       * - ...and all the style properties are either constant or come from the tokens
+       * - ...no keys need to be specified
+       * - this means that only one style object will be created per component + theme pair
+       */
+      [],
+    );
+
+    // merge the props from the tokens with anything passed in via style. This is internally cached via object identity
+    // so the merged style object won't change identity unless one of the two inputs changes identity.
+    const mergedStyle = mergeStyles(styleFromTokens, style);
+
+    // now just render the element, forwarding the props, setting the merged style, then passing the children as appropriate
+    return (
+      <Text {...rest} style={mergedStyle}>
+        {children}
+      </Text>
+    );
+  };
+
+  beforeEach(() => {
+    setActiveTheme();
+  });
+
+  /** first render the component with no updates */
+  it('Sample1Text rendering with no overrides', () => {
+    const tree = mount(<SampleText1>Sample1a</SampleText1>);
+    snapshotTestTree(tree);
+  });
+
+  /** now re-theme the component via the components in the theme */
+  it('Sample1Text rendering with some custom settings in the theme', () => {
+    setActiveTheme({
+      components: {
+        SampleText: {
+          color: 'pink',
+          fontSize: 24,
+        },
+      },
+    });
+    const tree = mount(<SampleText1>Sample1b</SampleText1>);
+    snapshotTestTree(tree);
+  });
+
+  /**
+   * Sample 2 - take the styled text component from the first example and allow color to be set in props as well. This is
+   * effectively saying that all other styles come from the theme except that color can be overriden via props.
+   */
+
+  /** use the props from the first sample and just add a color setting */
+  type Sample2Props = TextProps & { color?: string };
+
+  // the Sample2Text component is built the same way as sample1, just using the new hook that has been created
+  const SampleText2: React.FunctionComponent<Sample2Props> = (props) => {
+    const { color, style, children, ...rest } = props;
+    const theme = useTheme();
+
+    // this starts the same as sample1, extract tokens from the theme and get a theme specific cache object
+    const [tokens, cache] = useTokensSample1(theme);
+
+    // now when building up the style this time, the resulting style object is based upon both the theme and the passed
+    // in value of colors. Because the theme is already part of the cache definition, only color needs to be a key
+    const styleFromTokens = cache(
+      /** build the style, only patch the color if it has a value, otherwise the theme value would get stomped if color was undefined */
+      () => ({ ...tokens, ...(color && { color }) }),
+      /** use color as an additional key for the style */
+      [color],
+    );
+
+    // now just render, this time merging styles inline to make it a bit shorter
+    return (
+      <Text {...rest} style={mergeStyles(styleFromTokens, style)}>
+        {children}
+      </Text>
+    );
+  };
+
+  /** rendering the Sample2 component with the base theme */
+  it('Sample2Text rendering with defaults and a color override', () => {
+    const tree = mount(
+      <View>
+        <SampleText2>Sample2 with defaults</SampleText2>
+        <SampleText2 color="green">Sample2 with color override via prop</SampleText2>
+      </View>,
+    );
+    snapshotTestTree(tree);
+  });
+
+  /** now re-theme the component via the components in the theme */
+  it('Sample2Text rendering with some custom settings in the theme', () => {
+    setActiveTheme({
+      components: {
+        SampleText: {
+          fontSize: 18,
+          fontFamily: 'Helvetica',
+        },
+      },
+    });
+    const tree = mount(
+      <View>
+        <SampleText2>Sample2 with theme overrides set</SampleText2>
+        <SampleText2 color="purple">Sample2 with theme and color prop override</SampleText2>
+      </View>,
+    );
+    snapshotTestTree(tree);
+  });
+});