@edvisor/product-language 0.10.0 → 0.10.2

package/src/lib/helpers/generic-types.ts

@@ -0,0 +1,44 @@
+// eslint-disable-next-line no-restricted-syntax
+import React, { FC as FunctionComponent, ForwardRefExoticComponent, ForwardRefRenderFunction, PropsWithChildren as PWC, PropsWithoutRef, RefAttributes } from 'react'
+import { Slot } from './slots'
+
+/** @see https://stackoverflow.com/a/49725198/29182 */
+export type RequireOnlyOne<T, Keys extends keyof T = keyof T> = Pick<
+T,
+Exclude<keyof T, Keys>
+> &
+{
+  [K in Keys]-?: Required<Pick<T, K>> &
+    Partial<Record<Exclude<Keys, K>, undefined>>;
+}[Keys];
+
+export type MappedEnum<E, T> = {
+  [key in keyof E]: T;
+}
+
+export type Values<T> = T[keyof T];
+
+export type PropsWithChildren<T = unknown> = PWC<T>
+
+// Our FC type adds the ability to specify sub-components such as Slots
+// also, just good to wrap imports from 3rd parties in general
+export type FC<
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  P = {}, 
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  E extends { [x: symbol]: FunctionComponent<PropsWithChildren> | typeof Slot } = {}
+> = FunctionComponent<P> 
+  & { 
+    [key in keyof E]: E[key]
+  }
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+type ExtensibleForwardRef<T, P = {}, E = {}> = ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>
+  & {
+    [key in keyof E]: E[key]
+  }
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function forwardRef<T, P = {}, E = {}>(render: ForwardRefRenderFunction<T, P>): ExtensibleForwardRef<T, P, E> {
+  return React.forwardRef(render) as ExtensibleForwardRef<T, P, E>
+}

package/src/lib/helpers/index.ts

@@ -0,0 +1,8 @@
+export * from './safe-navigation'
+export * from './slots'
+export * from './generic-types'
+export * from './numbers'
+export * from './nothing'
+export * from './strings'
+export * from './isReactElementOfType'
+export * from './useInputElementState'

package/src/lib/helpers/isReactElementOfType.test.tsx

@@ -0,0 +1,108 @@
+import styled from 'styled-components'
+import { FC } from './generic-types'
+import { isReactElementOfType } from './isReactElementOfType'
+import { Slot } from './slots'
+import { Nothing } from './nothing'
+
+describe('isReactElementOfType', () => {
+  describe('class component', () => {
+    class Bob extends Slot {}
+
+    describe('both component and element are unstyled', () => {
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(Bob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(Bob)(<Bob />)).toBe(true)
+      })
+    })
+
+    describe('component type is styled', () => {
+      const StyledBob = styled(Bob)``
+
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(StyledBob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(StyledBob)(<Bob />)).toBe(true)
+      })
+    })
+
+    describe('element is styled', () => {
+      const StyledBob = styled(Bob)``
+
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(Bob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(Bob)(<StyledBob />)).toBe(true)
+      })
+    })
+
+    describe('both component and element are styled', () => {
+      const StyledBob = styled(Bob)``
+
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(StyledBob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(StyledBob)(<StyledBob />)).toBe(true)
+      })
+    })
+  })
+
+  describe('function component', () => {
+    const Bob: FC = () => <div />
+
+    describe('both component and element are unstyled', () => {
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(Bob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(Bob)(<Bob />)).toBe(true)
+      })
+    })
+
+    describe('component type is styled', () => {
+      const StyledBob = styled(Bob)``
+
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(StyledBob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(StyledBob)(<Bob />)).toBe(true)
+      })
+    })
+
+    describe('element is styled', () => {
+      const StyledBob = styled(Bob)``
+
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(Bob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(Bob)(<StyledBob />)).toBe(true)
+      })
+    })
+
+    describe('both component and element are styled', () => {
+      const StyledBob = styled(Bob)``
+
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(StyledBob)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(StyledBob)(<StyledBob />)).toBe(true)
+      })
+    })
+
+    describe('one of the components is Nothing', () => {
+      it('knows when they are different', () => {
+        expect(isReactElementOfType(Nothing)(<div />)).toBe(false)
+      })
+      it('knows when they are the same', () => {
+        expect(isReactElementOfType(Nothing)(<Nothing />)).toBe(true)
+      })
+    })
+  })
+})

package/src/lib/helpers/isReactElementOfType.ts

@@ -0,0 +1,42 @@
+import { PureComponent, ReactElement } from 'react'
+import { StyledComponent } from 'styled-components'
+import { FC, PropsWithChildren } from './generic-types'
+import { isDefined } from './safe-navigation'
+
+export const isReactElementOfType =
+  <P extends PropsWithChildren>(
+    // eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any
+    component: (StyledComponent<FC<P>, any> | FC<P> | typeof PureComponent) & {
+      // eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any
+      target?: any
+    }
+  ) =>
+  // eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any
+  (element?: any): element is ReactElement<P> => {
+    /**
+     * I'm going to leave this as a big if/else instead of a compound expression to make
+     * it clear exactly what we are checking.
+     */
+    if (element?.type === component) {
+      // component is a function or a class, and element is an element of that type
+      return true
+    } else if (element?.type?.target === component) {
+      // element is a styled element of the given component
+      // so we have to look at what it is styling (its target)
+      return true
+    } else if (isDefined(component?.target) && element?.type === component?.target) {
+      // component is the type of a styled component 
+      // and element is an element of the original unstyled component, 
+      // so we have to look at the target of the component itself (what it styled) 
+      return true
+    } else if (
+      isDefined(component?.target) &&
+      element?.type?.target === component?.target
+    ) {
+      // element and component are both styled, possibly _differently_ 
+      // but their underlying component type is the same
+      return true
+    }
+
+    return false
+  }

package/src/lib/helpers/nothing.tsx

@@ -0,0 +1,22 @@
+import { FC, PropsWithChildren } from './generic-types'
+import { isNil } from './safe-navigation'
+import { isReactElementOfType } from './isReactElementOfType'
+
+// eslint-disable-next-line no-null/no-null
+export const Nothing: FC = () => null
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const isNothing = isReactElementOfType(Nothing)
+
+export function maybeRender<T>(prop: T, JSX: JSX.Element) {
+  return isNil(prop) || (false === Boolean(prop)) || isNothing(prop) ? <Nothing /> : JSX
+}
+
+interface IIfProps {
+  is: unknown
+}
+
+export const If: FC<PropsWithChildren<IIfProps>> = (props) => {
+  // eslint-disable-next-line react/jsx-no-useless-fragment
+  return maybeRender(props.is, <>{props.children}</>)
+}

package/{lib/helpers/numbers.d.ts → src/lib/helpers/numbers.ts}

@@ -1,50 +1,67 @@
-export declare type Hex = `#${string}`;
-export declare function clamp(a: number, b: number, c: number): number;
-export declare function toHex(n: number, length: number): Hex;
-export declare function concatHex(a: Hex, b: Hex): Hex;
-/** given an array of boolean flags, bitwiseOr interprets them as an unsigned integer
- *
- * ```ts
- * bitwiseOr([false, true, false, true]) => 5 // 0b0101
- * ```
- *
- * This is useful for indexing into an enum:
- *
- * ```ts
- * const enum Level {
- *   default = 0,
- *   info = 0,
- *   danger = 1,
- *   warning = 2
- * }
- *
- * interface IProps {
- *  info?: boolean
- *  danger?: boolean
- *  warning?: boolean
- * }
- *
- * function toLevel(n: number): Level {
- *   switch (n) {
- *     case Level.info: return Level.info
- *     case Level.danger: return Level.danger
- *     case Level.warning: return Level.warning
- *     default: return Level.default
- *   }
- * }
- *
- * const level = bitwiseOr([props.info, props.danger, props.warning])
- *
- * const levelEnum = toLevel(level)
- * ```
-*/
-export declare function bitwiseOr(flags: unknown[]): number;
-/** given a number, it returns the number formed by the rightmost set bit as 1 and the 0s that comes after it
- *
- * ```ts
- * getRightmostSetBitNumber(12) => 4 // 12(1100) => 4(100)
- * getRightmostSetBitNumber(40) => 8 // 40(101000) => 8(1000)
- * ```
- *
- * */
-export declare function getRightmostSetBitNumber(n: number): number;
+export type Hex = `#${string}`
+
+export function clamp(a: number, b: number, c: number) {
+  return Math.max(a, Math.min(b, c))
+}
+
+export function toHex(n: number, length: number): Hex {
+  return `#${n.toString(16).padStart(length, '0').toUpperCase()}`
+}
+
+export function concatHex(a: Hex, b: Hex): Hex {
+  return `#${a.slice(1) + b.slice(1)}`
+}
+
+/** given an array of boolean flags, bitwiseOr interprets them as an unsigned integer
+ * 
+ * ```ts
+ * bitwiseOr([false, true, false, true]) => 5 // 0b0101
+ * ```
+ * 
+ * This is useful for indexing into an enum:
+ * 
+ * ```ts
+ * const enum Level {
+ *   default = 0,
+ *   info = 0,
+ *   danger = 1,
+ *   warning = 2
+ * }
+ * 
+ * interface IProps {
+ *  info?: boolean
+ *  danger?: boolean
+ *  warning?: boolean
+ * }
+ * 
+ * function toLevel(n: number): Level {
+ *   switch (n) {
+ *     case Level.info: return Level.info
+ *     case Level.danger: return Level.danger
+ *     case Level.warning: return Level.warning
+ *     default: return Level.default
+ *   }
+ * }
+ * 
+ * const level = bitwiseOr([props.info, props.danger, props.warning])
+ * 
+ * const levelEnum = toLevel(level)
+ * ```
+*/
+export function bitwiseOr(flags: unknown[]): number {
+  return flags.reduce((mask: number, flag, i) => mask | (Number(flag) << i), 0)
+}
+
+
+/** given a number, it returns the number formed by the rightmost set bit as 1 and the 0s that comes after it
+ * 
+ * ```ts
+ * getRightmostSetBitNumber(12) => 4 // 12(1100) => 4(100)
+ * getRightmostSetBitNumber(40) => 8 // 40(101000) => 8(1000)
+ * ```
+ * 
+ * */
+
+export function getRightmostSetBitNumber(n: number) {
+  return n & -n
+}

package/src/lib/helpers/safe-navigation.ts

@@ -0,0 +1,57 @@
+
+/** even though we have null disabled in the repo,
+ * I still would not want isNil to skip checking null
+ * it is for juuuuust in case a third party sends us a null
+ * or something, and the types are not correct
+ */
+
+/* eslint-disable no-null/no-null */
+/* eslint-disable @typescript-eslint/ban-types */
+
+export function isNil<T>(value: T | undefined | null): value is undefined | null {
+  return value === null || value === undefined
+}
+
+export function isDefined<T>(value: T | undefined | null): value is T {
+  return !isNil(value)
+}
+
+export function defaultTo<T>(value: T | undefined | null, fallback: T): T {
+  return isDefined(value) ? value : fallback
+}
+
+export function isEmpty<T extends { length: number }>(obj: T) {
+  return obj.length < 1
+}
+
+/** used for evaluating tri-state logic (true | false | undefined) */
+export function is (pred?: boolean): boolean {
+  return isDefined(pred) && pred
+}
+
+export function toArray<T>(obj: T | T[] | undefined | null): T[] {
+  return isDefined(obj) ? Array.isArray(obj) ? obj : [obj] : []
+}
+
+export function safeArray<T>(arr: T[] | undefined | null): T[] {
+  return isDefined(arr) ? arr : []
+}
+
+export function safeCallback <T>(f?: (e: T) => void, e?: T) {
+  if (isDefined(f)) {
+    if (isDefined(e)) {
+      f(e)
+    } else {
+      (f as () => void)()
+    }
+  }
+}
+
+export {
+  first, 
+  isString, 
+  isFunction,
+  uniqueId,
+  debounce,
+  throttle,
+} from 'lodash'

package/src/lib/helpers/slots.tsx

@@ -0,0 +1,126 @@
+import { Children, CSSProperties, PureComponent, ReactElement, ReactNode } from 'react'
+import { FC, PropsWithChildren } from './generic-types'
+import { Nothing } from './nothing'
+import { isDefined, isFunction, isNil } from './safe-navigation'
+
+/** 
+ * @TODO these aren't quiiiiite right
+ * 
+ * They all say they return ReactNode but I feel like JSX.Element or something
+ * is more accurate? The child type needs to include _anything react can render_
+ * but it should also allow the caller to cloneElement on the results so that
+ * they can do stuff like
+ * 
+ * const sections = getSlots(Section, children)
+ *  .map((el, i) => i === 0 ? cloneElement(el, { first: true }) : el)
+ * 
+ * Right? I want this...
+ * */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isReactElement (obj?: any): obj is ReactElement {
+  // eslint-disable-next-line no-prototype-builtins
+  return isDefined(obj) && obj.hasOwnProperty('type')
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const isSlotOfType = <T extends typeof Slot>(type: T | FC) => (obj?: any): obj is T => {
+  return (
+    (isDefined(obj) &&
+      isReactElement(obj) &&
+      isDefined(obj.type) &&
+      (Object.getPrototypeOf(obj.type) === type || obj.type === type)) ||
+    (isDefined(obj.type) &&
+      isDefined(obj.type.target) &&
+      (Object.getPrototypeOf(obj.type.target) === type ||
+        obj.type.target === type))
+  )
+}
+
+const findSlotByType = <T extends typeof Slot>(type: T, children?: ReactNode): ReactElement => {
+  return Children.toArray(children).find(isSlotOfType(type)) as ReactElement
+}
+
+const filterSlotByType = <T extends typeof Slot>(type: T, children?: ReactNode): ReactElement[] => {
+  return Children.toArray(children).filter(isSlotOfType(type)) as ReactElement[]
+}
+
+export class Slot<T = unknown> extends PureComponent<PropsWithChildren<T>> {
+  override render () {
+    return this.props.children
+  }
+}
+
+export class StylableSlot extends Slot {
+  override render () {
+    return <div {...this.props}>{this.props.children}</div>
+  }
+}
+
+/** gets children that are _not_ slots */
+export function getOtherChildren(children?: ReactNode): ReactNode[] {
+  return Children.toArray(children).filter((child) => !isSlotOfType(Slot)(child))
+}
+
+export function getSlots<T extends typeof Slot>(slot: T, children?: ReactNode): ReactElement[] {
+  const result = filterSlotByType(slot, children)
+
+  if (isNil(result)) {
+    return []
+  }
+
+  return result
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function hasProps (obj: any): obj is { props: { children: ReactNode }} {
+  // eslint-disable-next-line no-prototype-builtins
+  return isDefined(obj) && obj.hasOwnProperty('props')
+}
+
+export function getSlot<T extends typeof Slot>(slot: T, children?: ReactNode): ReactElement {
+  const result = findSlotByType(slot, children)
+
+  if (isNil(result)) {
+    return <Nothing />
+  }
+
+  if (hasProps(result)) {
+    return result
+  }
+
+  return result
+}
+
+/** given a ReactElement, like a child, apply the given props to it */
+export function applyProps<T>(element: ReactElement<T>, props: Partial<T>): ReactElement
+export function applyProps<T>(element: ReactElement<T>, props: Partial<T> | ((props: T) => T)): ReactElement {
+  if (isFunction(props)) {
+    return {
+      ...element,
+      props: props(element.props)
+    }
+  }
+
+  return {
+    ...element,
+    props: {
+      ...element.props,
+      ...props,
+    },
+  }
+}
+
+/** given a ReactElement, like a child, apply the given styles to it, merging with the existing styles */
+export function applyStyle(element: ReactElement, style: CSSProperties): ReactElement {
+  return {
+    ...element,
+    props: {
+      ...element.props,
+      style: {
+        ...element.props.style,
+        ...style,
+      },
+    },
+  }
+}

package/src/lib/helpers/strings.test.ts

@@ -0,0 +1,47 @@
+import { toKebabCase } from './strings'
+
+describe('strings', () => {
+  describe('toKebabCase', () => {
+    it('sends camel case to kebab case', () => {
+      const result = toKebabCase('helloMyFriends')
+
+      expect(result).toBe('hello-my-friends')
+    })
+    
+    it('sends leading caps to kebab case', () => {
+      const result = toKebabCase('HelloMyFriends')
+
+      expect(result).toBe('hello-my-friends')
+    })
+
+    it('respects numbers', () => {
+      const result = toKebabCase('Section1IsGood')
+
+      expect(result).toBe('section-1-is-good')
+    })
+    
+    it('respects leading and trailing numbers', () => {
+      const result = toKebabCase('1Section1')
+
+      expect(result).toBe('1-section-1')
+    })
+
+    it('removes non-alphanumeric characters, such as whitespace and punctuation', () => {
+      const result = toKebabCase('Help Text. Lorem Ipsum')
+
+      expect(result).toBe('help-text-lorem-ipsum')
+    })
+
+    it('removes leading and trailing nonsense', () => {
+      const result = toKebabCase('__Foo_Bar__')
+
+      expect(result).toBe('foo-bar')
+    })
+
+    it('removes leading and trailing whitespace', () => {
+      const result = toKebabCase(' . Foo_Bar_ _ . ')
+
+      expect(result).toBe('foo-bar')
+    })
+  })
+})

package/src/lib/helpers/strings.ts

@@ -0,0 +1,16 @@
+import { isDefined } from './safe-navigation'
+
+export const toKebabCase = (str: string) => {
+  return isDefined(str)
+    ? str
+        .replace(/[^a-zA-Z0-9\\-]/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/([0-9]+)(.*)/g, '$1-$2')
+        .replace(/(.*)([0-9]+)/g, '$1-$2')
+        .replace(/^[\s_]+/g, '')
+        .replace(/[\s_]+$/g, '')
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-zA-Z0-9\\-]/g, '')
+        .toLowerCase()
+    : ''
+}

package/src/lib/helpers/useInputElementState.ts

@@ -0,0 +1,56 @@
+/* eslint-disable no-console */
+import { useState, useEffect } from 'react'
+import { isDefined, isNil } from './safe-navigation'
+
+const READ_ONLY_WARNING = 'Warning: You provided a `value` prop to a form field without an `onChange` handler. This will render a read-only field. If the field should be mutable use `defaultValue`. Otherwise, set either `onChange` or `readOnly`'
+const UNCONTROLLED_TO_CONTROLLED = 'Warning: A component is changing an uncontrolled input to be controlled. This is likely caused by the value changing from undefined to a defined value, which should not happen. Decide between using a controlled or uncontrolled input element for the lifetime of the component. More info: https://reactjs.org/link/controlled-components'
+const CONTROLLED_TO_UNCONTROLLED = 'Warning: A component is changing a controlled input to be uncontrolled. This is likely caused by the value changing from a defined to undefined, which should not happen. Decide between using a controlled or uncontrolled input element for the lifetime of the component. More info: https://reactjs.org/link/controlled-components'
+
+type IInputElementState<T> = [
+  T | undefined,
+  (change: T) => void
+]
+
+/**
+ * 
+ * This hook is to help implement a common pattern:
+ * 
+ * <input onChange={doSomething} /> // uncontrolled
+ * <input value={1} /> // should be marked read only
+ * <input value={state} onChange={setState} /> // controlled
+ * 
+ * I've reimplemented this logic a few times, but now I have a nice helper :D
+ * 
+ * const [state, setState] = useInputElementState({
+ *   value: props.value,
+ *   defaultValue: props.defaultValue, // the value to use if value is undefined
+ *   onChange: props.onChange,
+ * })
+ * 
+ * if you give it nothing, you get state, setState for internal state management (uncontrolled input)
+ * if you give it value only, you get a warning
+ * if you give it value and onChange, state management if deferred to the parent (controlled input)
+ */
+export function useInputElementState<T>(props: { value?: T, defaultValue?: T, onChange?: (change: T) => void }): IInputElementState<T> {
+  const [initialValue] = useState(props.value)
+  const [state, setState] = useState(props.defaultValue)
+
+  const { value = state, onChange = setState } = props
+
+  useEffect(() => {
+    if (initialValue === undefined && props.value !== undefined) {
+      console.error(UNCONTROLLED_TO_CONTROLLED)
+    } else if (initialValue !== undefined && props.value === undefined) {
+      console.error(CONTROLLED_TO_UNCONTROLLED)
+    }
+  }, [props.value, initialValue])
+
+  if ( isDefined(props.value) && isNil(props.onChange)) {
+    console.error(READ_ONLY_WARNING)
+  }
+
+  return [
+    value,
+    onChange,
+  ]
+}

package/src/lib/helpers/useKeyDown.ts

@@ -0,0 +1,17 @@
+import { useEffect } from 'react'
+
+export function useKeyDown(targetKey: string, handler: () => void) {
+  function downHandler({ key }: { key: string}) {
+    if (key === targetKey) {
+      handler()
+    }
+  }
+
+  useEffect(() => {
+    window.addEventListener('keydown', downHandler)
+    return () => {
+      window.removeEventListener('keydown', downHandler)
+    }
+  }, [])
+  return
+}