@fluentui-react-native/framework-base 0.1.1

package/src/memo-cache/getCacheEntry.test.ts

@@ -0,0 +1,120 @@
+import type { CacheEntry } from './getCacheEntry';
+import { getCacheEntry } from './getCacheEntry';
+
+interface TestObj {
+  id: number;
+}
+
+type TestEntry = CacheEntry<TestObj>;
+
+function compareResults(base: TestEntry, args: any[], argsNoMatch?: any[]): void {
+  const e1 = getCacheEntry(base, args);
+  expect(getCacheEntry(base, args)).toBe(e1);
+
+  if (argsNoMatch) {
+    expect(getCacheEntry(base, argsNoMatch)).not.toBe(e1);
+  }
+}
+
+describe('Memo cache unit tests', () => {
+  test('undefined args to return noargs', () => {
+    const base: TestEntry = {};
+    expect(getCacheEntry(base, undefined)).toBe(base.noargs);
+  });
+
+  test('empty args array to return noargs entry', () => {
+    const base: TestEntry = {};
+    expect(getCacheEntry(base, [])).toBe(base.noargs);
+  });
+
+  test('undefined goes to empty entry', () => {
+    const base: TestEntry = {};
+    expect(getCacheEntry(base, [undefined])).toBe(base.empty);
+  });
+
+  test('null to go to empty entry', () => {
+    const base: TestEntry = {};
+    expect(getCacheEntry(base, [null])).toBe(base.empty);
+  });
+
+  test('string gets keyed correctly', () => {
+    const base: TestEntry = {};
+    const key = 'foo';
+    expect(getCacheEntry(base, [key])).toBe(base.str[key]);
+  });
+
+  test('number gets keyed correctly', () => {
+    const base: TestEntry = {};
+    const val = 235;
+    const key = val + '';
+    expect(getCacheEntry(base, [val])).toBe(base.str[key]);
+  });
+
+  test('bool gets keyed correctly', () => {
+    const base: TestEntry = {};
+    const val = true;
+    const key = val + '';
+    expect(getCacheEntry(base, [val])).toBe(base.str[key]);
+  });
+
+  test('false bool gets keyed correctly', () => {
+    const base: TestEntry = {};
+    const val = false;
+    const key = val + '';
+    expect(getCacheEntry(base, [val])).toBe(base.str[key]);
+  });
+
+  test('object gets keyed correctly', () => {
+    const base: TestEntry = {};
+    const key = {};
+    expect(getCacheEntry(base, [key])).toBe(base.obj.get(key));
+  });
+
+  test('function gets keyed correctly', () => {
+    const base: TestEntry = {};
+    const key = () => {
+      return 'hello world';
+    };
+    expect(getCacheEntry(base, [key])).toBe(base.obj.get(key));
+  });
+
+  test('basic string retrieval', () => {
+    compareResults({}, ['hello', 'world'], ['hello world']);
+  });
+
+  test('mixed keys with strings', () => {
+    compareResults({}, ['hello', 1, true, undefined, 'world'], ['hello', 1, true, '', 'world']);
+  });
+
+  test('basic object matches', () => {
+    const obj = {};
+    compareResults({}, [obj]);
+  });
+
+  test('mixed object and string matches', () => {
+    const obj = {};
+    compareResults({}, [obj, 'hello', 1, 'world']);
+  });
+
+  test('mixed obj and strings with obj at end', () => {
+    const obj = {};
+    const obj2 = {};
+    compareResults({}, ['hello', 1, 'world', obj], ['hello', 1, 'world', obj2]);
+  });
+
+  test('hybrid sets', () => {
+    const obj = {};
+    const obj2 = {};
+    compareResults({}, ['hello', obj, 'world', 1, false, obj2, undefined]);
+  });
+
+  test('sub cache on object', () => {
+    const obj = {};
+    const args1 = ['hello', obj];
+    const base = {};
+    const subRoot = getCacheEntry(base, args1);
+    const args2 = ['world', base];
+    const target = getCacheEntry(subRoot, args2);
+    expect(getCacheEntry(base, [...args1, ...args2])).toBe(target);
+  });
+});

package/src/memo-cache/getCacheEntry.ts

@@ -0,0 +1,67 @@
+export type CacheEntry<T, TGet = any> = {
+  /** stores the cached value if any */
+  value?: T;
+
+  /** entry used for undefined and null values, these both collapse to the same type */
+  empty?: CacheEntry<TGet>;
+
+  /** entry used for the case where the array of args is null or length 0 */
+  noargs?: CacheEntry<TGet>;
+
+  /** all remaining non-object types are keyed as strings for lookups */
+  str?: { [key: string]: CacheEntry<TGet> };
+
+  /** object types are keyed in a weak map on object identity */
+  obj?: WeakMap<object, TGet>;
+};
+
+/**
+ * just wraps the common entry.foo = entry.foo || {} pattern
+ * @param entry - entry to ensure a key value for
+ * @param key - which key of that entry to ensure the value for
+ */
+function ensureAndReturn(entry: CacheEntry<any>, key: keyof CacheEntry<any>): CacheEntry<any> | { [key: string]: CacheEntry<any> } {
+  if ((key as string) === '__proto__' || (key as string) === 'constructor' || (key as string) === 'prototype') {
+    throw new Error('Invalid key');
+  }
+  return (entry[key] = entry[key] || {});
+}
+
+/**
+ * Step one level deeper in the cache, based on the key value from the current location
+ *
+ * @param entry - base entry to work from
+ * @param val - value to use as the key for progressing to the next level of the cache
+ */
+function jumpToCacheEntry(entry: CacheEntry<any>, val: any): CacheEntry<any> {
+  if (val === undefined || val === null) {
+    // undefined or null just routes directly to the empty object.  This avoids the issues of string collisions with 'null' or 'undefined'
+    // when using the string key map, it also avoids creating the WeakMap (since null is technically typoef object), particularly in cases
+    // where null is just being set on non-object types.
+    return ensureAndReturn(entry, 'empty');
+  }
+  if (typeof val === 'object' || typeof val === 'function') {
+    // objects and functions will be treated as key values in a WeakMap
+    const byObj = (entry.obj = entry.obj || new WeakMap<object, CacheEntry<any>>());
+    return byObj.get(val) || byObj.set(val, {}).get(val);
+  }
+  // otherwise convert everything to a string and store it in the str object (using it as a map)
+  const key = val + '';
+  const byString = ensureAndReturn(entry, 'str');
+  return (byString[key] = byString[key] || {});
+}
+
+/**
+ * Given a base entry, either traverse or build the cache tree that matches the provided args
+ *
+ * @param entry - entry to use as the base of the cache walk
+ * @param args - array of arguments to use to progress deeper into the cache
+ */
+export function getCacheEntry<T, TGet = any>(entry: CacheEntry<T>, args: any[]): CacheEntry<TGet> {
+  // in the case where the args array exists and is > 0 length:
+  // - walk the cache from entry, like a linked list, jumping to the next entry by key, building it up as you go
+  // - otherwise if there are no args just use the noargs branch
+  return args && args.length > 0
+    ? (args.reduce((previous: CacheEntry<any>, arg: any) => jumpToCacheEntry(previous, arg), entry) as CacheEntry<TGet>)
+    : ensureAndReturn(entry, 'noargs');
+}

package/src/memo-cache/getMemoCache.test.ts

@@ -0,0 +1,91 @@
+import { getMemoCache } from './getMemoCache';
+
+interface TestObj {
+  id: number;
+}
+
+function getObjFactory() {
+  const obj: TestObj = { id: 0 };
+  return () => ({
+    id: obj.id++,
+  });
+}
+
+describe('getMemoCache unit tests', () => {
+  test('memoValue with null function', () => {
+    const memoValue = getMemoCache();
+    const [val] = memoValue(null, ['foo', 'bar']);
+    expect(val).toBeNull();
+  });
+
+  test('memoValue with undefined', () => {
+    const memoValue = getMemoCache();
+    const [val] = memoValue(undefined, ['foo', 'bar']);
+    expect(val).toBeUndefined();
+  });
+
+  test('memoValue with string', () => {
+    const memoValue = getMemoCache();
+    const [val] = memoValue('foo', ['bar', 'baz']);
+    expect(val).toEqual('foo');
+  });
+
+  test('memoValue with object', () => {
+    const memoValue = getMemoCache();
+    const obj = { foo: 'hello', bar: 2, baz: 'you' };
+    const [val] = memoValue(obj, ['hello', obj]);
+    expect(val).toBe(obj);
+  });
+
+  test('memoValue executes function', () => {
+    const memoValue = getMemoCache();
+    const fn = getObjFactory();
+    const v1 = fn();
+    const [v2] = memoValue(fn, ['bar', 'baz']);
+    expect(v1).not.toBe(v2);
+    expect(v1.id).not.toEqual(v2.id);
+  });
+
+  test('memo calls function only once', () => {
+    const memoValue = getMemoCache();
+    const fn = getObjFactory();
+    const keys = ['hello', 'world'];
+    const [o1] = memoValue(fn, keys);
+    const [o2] = memoValue(fn, keys);
+    expect(o2).toBe(o1);
+  });
+
+  test('memo calls function only once for empty inputs', () => {
+    const memoValue = getMemoCache();
+    const fn = getObjFactory();
+    const [o1] = memoValue(fn, undefined);
+    const [o2] = memoValue(fn, undefined);
+    expect(o2).toBe(o1);
+  });
+
+  test('sub caches are separate', () => {
+    const memoValue = getMemoCache();
+    const base1 = {};
+    const base2 = {};
+    const [, getCache1] = memoValue(null, [base1]);
+    const [, getCache2] = memoValue(null, [base2]);
+    const objKey = {};
+    const fn = getObjFactory();
+    const [o1] = getCache1(fn, [objKey]);
+    const [o2] = getCache2(fn, [objKey]);
+    const [o3] = getCache2(fn, [objKey]);
+    expect(o1).not.toBe(o2);
+    expect(o3).toBe(o2);
+  });
+
+  test('sub caches work on branches', () => {
+    const memoValue = getMemoCache();
+    const keys1 = [{}, 2, 'hello'];
+    const keys2 = [{}, true];
+    const fn = getObjFactory();
+    const [, getMemoValue] = memoValue(null, keys1);
+    const [val1] = getMemoValue(fn, keys2);
+    const [val2] = memoValue(fn, [...keys1, ...keys2]);
+    expect(val2).toBe(val1);
+  });
+});

package/src/memo-cache/getMemoCache.ts

@@ -0,0 +1,37 @@
+import type { CacheEntry } from './getCacheEntry';
+import { getCacheEntry } from './getCacheEntry';
+
+export type ValueFactory<T> = () => T;
+
+/** signature for the cache function */
+export type GetMemoValue<T, TGet = any> = (factory: T | ValueFactory<T>, keys: any[]) => [T, GetMemoValue<TGet>];
+
+/** base node used to remember references when a globalKey is set */
+const _baseEntry: CacheEntry<any> = {};
+
+/**
+ * Primary functional worker used to implement the caching pattern
+ *
+ * @param entry - entry to use as the base of the cache traversal
+ * @param factory - generally a function who's results will be cached, and returned via the set of keys
+ * @param keys - an ordered array of values of any type, used as keys to look up the entry
+ */
+function getMemoValueWorker<T, TGet = any>(entry: CacheEntry<any>, factory: T | ValueFactory<T>, keys: any[]): [T, GetMemoValue<TGet>] {
+  const foundEntry = getCacheEntry(entry, keys);
+  // check the key being set, not the value to disambiguate an undefined factory result/value from never having run the factory
+  if (!foundEntry.hasOwnProperty('value')) {
+    foundEntry.value = typeof factory === 'function' ? (factory as ValueFactory<T>)() : factory;
+  }
+  return [foundEntry.value, (fact: TGet | ValueFactory<TGet>, args: any[]) => getMemoValueWorker<TGet>(foundEntry, fact, args)];
+}
+
+/**
+ * Get a memo cache instance, this can either be completely self-contained or associated with a global key
+ *
+ * @param globalKey - optional object reference to use as a key for this cache.  If specified it can be used
+ * to retrieve the same cache from the global call.  If not specified the returned cache will be completely isolated.
+ */
+export function getMemoCache<T = any>(globalKey?: object): GetMemoValue<T> {
+  const entry = globalKey ? getCacheEntry(_baseEntry, [globalKey]) : {};
+  return (fact: T | ValueFactory<T>, args: any[]) => getMemoValueWorker<T>(entry, fact, args);
+}

package/src/memo-cache/index.ts

@@ -0,0 +1,3 @@
+export type { GetMemoValue } from './getMemoCache';
+export { getMemoCache } from './getMemoCache';
+export { memoize } from './memoize';

package/src/memo-cache/memoize.test.ts

@@ -0,0 +1,48 @@
+import { memoize } from './memoize';
+
+let _globalCalls = 0;
+
+describe('Memoize unit tests', () => {
+  test('simple function no args', () => {
+    const noArgsFn = memoize(() => {
+      return ++_globalCalls;
+    });
+    const result1 = noArgsFn();
+    expect(noArgsFn()).toEqual(result1);
+  });
+
+  test('simple function 1 arg', () => {
+    const incrementFn = memoize((bump: number) => {
+      ++_globalCalls;
+      return bump + 1;
+    });
+
+    expect(incrementFn(3)).toEqual(4);
+    const calls = _globalCalls;
+    incrementFn(3);
+    expect(_globalCalls).toEqual(calls);
+    incrementFn(4);
+    expect(_globalCalls).toEqual(calls + 1);
+    incrementFn(4);
+    expect(_globalCalls).toEqual(calls + 1);
+  });
+
+  test('void function 2 args', () => {
+    const voidFn = memoize((a: number, b: string) => {
+      if (a) {
+        ++_globalCalls;
+      } else if (b) {
+        ++_globalCalls;
+      } else {
+        ++_globalCalls;
+      }
+    });
+
+    voidFn(3, 'hello');
+    const calls = _globalCalls;
+    voidFn(3, 'hello');
+    expect(_globalCalls).toEqual(calls);
+    voidFn(3, 'world');
+    expect(_globalCalls).toEqual(calls + 1);
+  });
+});

package/src/memo-cache/memoize.ts

@@ -0,0 +1,17 @@
+import { getMemoCache } from './getMemoCache';
+
+/**
+ * This wraps a function to memoize the results using the standard javascript memoization pattern
+ * @param fn - function to memoize
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function memoize<T extends Function>(fn: T): T {
+  // create a unique cache that will be captured in the closure
+  const cache = getMemoCache<any>();
+  // create the closure which wraps the calling function
+  const closure = (...args: any[]) => {
+    return cache(() => fn(...(args || [])), args)[0];
+  };
+  // now return that closure strongly typed as the function.
+  return closure as unknown as T;
+}

package/src/merge-props/index.ts

@@ -0,0 +1,3 @@
+export type { StyleProp } from './mergeStyles.types';
+export { mergeStyles } from './mergeStyles';
+export { mergeProps } from './mergeProps';

package/src/merge-props/mergeProps.ts

@@ -0,0 +1,20 @@
+import type { MergeOptions } from '../immutable-merge/Merge';
+import { immutableMergeCore, filterToObjects } from '../immutable-merge/Merge';
+
+import { mergeStyles } from './mergeStyles';
+
+/**
+ * Props will not deeply merge with the exception of a style property.  Also className needs to be handled specially.
+ */
+const mergePropsOptions: MergeOptions = {
+  className: (...names: any[]) => names.filter((v) => v && typeof v === 'string').join(' '),
+  style: mergeStyles,
+};
+
+/**
+ * Merge props together, flattening and merging styles as appropriate
+ * @param props - props to merge together
+ */
+export function mergeProps<TProps>(...props: (TProps | undefined)[]): TProps {
+  return immutableMergeCore(mergePropsOptions, ...filterToObjects<TProps>(props));
+}

package/src/merge-props/mergeStyles.test.ts

@@ -0,0 +1,124 @@
+import type { ColorValue } from 'react-native';
+
+import { flattenStyle, mergeAndFlattenStyles, mergeStyles } from './mergeStyles';
+import type { StyleProp } from './mergeStyles.types';
+
+interface IFakeStyle {
+  backgroundColor?: ColorValue;
+  color?: ColorValue;
+  fontFamily?: string;
+  borderWidth?: number;
+  ':hover'?: IFakeStyle;
+}
+
+type IFakeStyleProp = StyleProp<IFakeStyle>;
+
+const s1: IFakeStyleProp = [
+  { backgroundColor: 'blue' },
+  [{ color: 'red', borderWidth: 1 }, { fontFamily: 'segoe' }, [{ backgroundColor: 'bodyBackground' }]],
+];
+
+const s1flatten: IFakeStyleProp = {
+  backgroundColor: 'bodyBackground',
+  color: 'red',
+  borderWidth: 1,
+  fontFamily: 'segoe',
+};
+
+const s2: IFakeStyleProp = {
+  borderWidth: 2,
+  fontFamily: 'primary',
+  color: 'bodyText',
+};
+
+const sMerged: IFakeStyleProp = {
+  backgroundColor: 'bodyBackground',
+  borderWidth: 2,
+  fontFamily: 'primary',
+  color: 'bodyText',
+};
+
+const sSelector: IFakeStyleProp = {
+  borderWidth: 1,
+  ':hover': {
+    borderWidth: 2,
+    fontFamily: 'primary',
+  },
+};
+
+const sSelector2: IFakeStyleProp = {
+  backgroundColor: 'white',
+  ':hover': {
+    backgroundColor: 'black',
+    borderWidth: 3,
+  },
+};
+
+const sArraySelector: IFakeStyleProp = [[sSelector]];
+
+const sArraySelector2: IFakeStyleProp = [sSelector2];
+
+const sMergedSelectors: IFakeStyleProp = {
+  borderWidth: 1,
+  backgroundColor: 'white',
+  ':hover': {
+    borderWidth: 3,
+    fontFamily: 'primary',
+    backgroundColor: 'black',
+  },
+};
+
+describe('Style flatten and merge tests', () => {
+  test('flatten recursive arrays', () => {
+    const flattened = flattenStyle(s1);
+    expect(flattened).toEqual(s1flatten);
+    expect(flattened).not.toBe(s1);
+  });
+
+  test('flatten flat style returns style', () => {
+    const flattened = flattenStyle(s2);
+    expect(flattened).toBe(s2);
+  });
+
+  test('merge also flattens', () => {
+    const merged = mergeAndFlattenStyles(undefined, undefined, s1, s2);
+    expect(merged).toEqual(sMerged);
+  });
+
+  test('merge with sub objects', () => {
+    const merged = mergeAndFlattenStyles(undefined, undefined, sSelector, sSelector2);
+    expect(merged).toEqual(sMergedSelectors);
+  });
+
+  test('merge sub objects in arrays', () => {
+    const merged = mergeAndFlattenStyles(undefined, undefined, sArraySelector, sArraySelector2);
+    expect(merged).toEqual(sMergedSelectors);
+  });
+
+  test('memo recursive arrays', () => {
+    const flattened = mergeStyles(s1);
+    const flattened2 = mergeStyles(s1);
+    expect(flattened).toEqual(s1flatten);
+    expect(flattened2).toBe(flattened);
+  });
+
+  test('memo flat style', () => {
+    const flattened = mergeStyles(s2);
+    const flattened2 = mergeStyles(s2);
+    expect(flattened).toBe(s2);
+    expect(flattened2).toBe(flattened);
+  });
+
+  test('memo and flatten multiple', () => {
+    const flattened = mergeStyles(s1, s2);
+    const flattened2 = mergeStyles(s1, s2);
+    expect(flattened).toEqual(sMerged);
+    expect(flattened2).toBe(flattened);
+  });
+
+  test('memo styles ignores undefined values', () => {
+    const result1 = mergeStyles(s1, s2, undefined, s1flatten);
+    const result2 = mergeStyles(s1, undefined, s2, s1flatten);
+    expect(result2).toBe(result1);
+  });
+});

package/src/merge-props/mergeStyles.ts

@@ -0,0 +1,40 @@
+import { immutableMerge } from '../immutable-merge/Merge';
+import { getMemoCache } from '../memo-cache/getMemoCache';
+
+import type { StyleProp } from './mergeStyles.types';
+
+/**
+ * Take a react-native style, which may be a recursive array, and return as a flattened
+ * style.  This is analagous to the flatten routine that is part of the style sheet API
+ *
+ * @param style - StyleProp<TStyle> to flatten, this can be a TStyle or an array
+ */
+export function flattenStyle(style: StyleProp<object>): object {
+  return Array.isArray(style) ? immutableMerge(...style.map((v) => flattenStyle(v))) : style || {};
+}
+
+/**
+ * Merge styles together into a single flat object and optionally finalize them, can also be used to finalize a single style
+ *
+ * @param styles - array of styles to merge together.  The styles will be flattened as part of the process
+ */
+export function mergeAndFlattenStyles(...styles: StyleProp<object>[]): object | undefined {
+  // baseline merge and flatten the objects
+  return immutableMerge(
+    ...styles.map((styleProp: StyleProp<object>) => {
+      return flattenStyle(styleProp);
+    }),
+  );
+}
+
+const _styleCache = getMemoCache();
+
+export function mergeStyles(...styles: StyleProp<object>[]): object | undefined {
+  // filter the style set to just objects (which might be arrays or plain style objects)
+  const inputs = styles.filter((s) => typeof s === 'object') as object[];
+
+  // now memo the results if there is more than one element or if the one element is an array
+  return inputs.length > 1 || (inputs.length === 1 && Array.isArray(inputs[0]))
+    ? _styleCache(() => mergeAndFlattenStyles(undefined, ...inputs), inputs)[0]
+    : inputs[0] || {};
+}

package/src/merge-props/mergeStyles.types.ts

@@ -0,0 +1,9 @@
+/**
+ * This is a copy of the react-native style prop type, copied here to avoid RN dependencies for web clients
+ */
+type Falsy = undefined | null | false;
+type RecursiveArray<T> = (T | RecursiveArray<T>)[];
+/** Keep a brand of 'T' so that calls to `StyleSheet.flatten` can take `RegisteredStyle<T>` and return `T`. */
+type RegisteredStyle<T> = number & { __registeredStyleBrand: T };
+
+export type StyleProp<T> = T | RegisteredStyle<T> | RecursiveArray<T | RegisteredStyle<T> | Falsy> | Falsy;