@codeleap/utils 6.3.0 → 6.8.0

package/src/react.tsx

@@ -2,6 +2,7 @@ import equals from 'deep-equal'
 import React from 'react'
 import { TypeGuards } from '@codeleap/types'
 
+/** Deep structural equality backed by the `deep-equal` package. */
 export const deepEqual = equals
 
 type ArePropsEqualOptions<MergedObject> = {
@@ -9,6 +10,13 @@ type ArePropsEqualOptions<MergedObject> = {
   excludeKeys?: string[]
 }
 
+/**
+ * Checks a specific subset of props for deep equality between two render cycles.
+ *
+ * `excludeKeys` are deleted from each compared value **in place** before
+ * comparison — this mutates the items inside `previous` and `next`.
+ * Pass only the keys you want to ignore, and be aware of the side-effect.
+ */
 export function arePropsEqual<A, B>(
   previous: A,
   next: B,
@@ -17,8 +25,8 @@ export function arePropsEqual<A, B>(
   const { check, excludeKeys = [] } = options
 
   for (const c of check) {
-    const nextItem = next[c as string]
-    const prevItem = previous[c as string]
+    const nextItem = (next as any)[c as string]
+    const prevItem = (previous as any)[c as string]
 
     for (const key of excludeKeys) {
       if (nextItem?.[key]) delete nextItem[key]
@@ -35,20 +43,35 @@ export function arePropsEqual<A, B>(
   return true
 }
 
-export const flattenChildren = (children, flat = []) => {
+/**
+ * Recursively collects a React children tree into a single flat array.
+ *
+ * Uses `React.Children.toArray` at each level (which assigns stable keys), then
+ * follows any `children` prop on the top-level element to continue flattening.
+ * Only one level of `props.children` nesting is followed per call — deeply
+ * nested component trees (not just wrapper nodes) are not fully unwound.
+ */
+export const flattenChildren = (children: any, flat: React.ReactNode[] = []): React.ReactNode[] => {
   flat = [...flat, ...React.Children.toArray(children)]
 
-  if (children.props && children.props.children) {
+  if (children?.props && children.props.children) {
     return flattenChildren(children.props.children, flat)
   }
 
   return flat
 }
 
-export const simplifyChildren = children => {
+/**
+ * Flattens a children tree and strips the `children` prop from each element's
+ * props, returning a serialisable summary of the tree.
+ *
+ * Intended for introspection and testing — not for re-rendering, since `ref`
+ * and event-handler functions are preserved as-is.
+ */
+export const simplifyChildren = (children: any) => {
   const flat = flattenChildren(children)
 
-  return flat.map(
+  return (flat as any[]).map(
     ({
       key,
       ref,
@@ -63,6 +86,18 @@ export const simplifyChildren = children => {
   )
 }
 
+/**
+ * Renders a slot that accepts a component, a props object, or a pre-rendered node.
+ *
+ * Resolution order:
+ * 1. If `ComponentOrProps` is a function → render it as `<ComponentOrProps {...props} />`.
+ * 2. If it is `null`, `undefined`, or an empty object → return `null`.
+ * 3. If it is already a valid React element → return it as-is.
+ * 4. Otherwise treat it as a props object and render `<DefaultComponent {...props} {...ComponentOrProps} />`.
+ *
+ * This lets call sites pass either a component override, extra props, or nothing,
+ * without needing separate conditional rendering logic.
+ */
 export function getRenderedComponent<P = any>(
   ComponentOrProps: React.ComponentType<P> | P | React.ReactNode | null | undefined,
   DefaultComponent: React.ComponentType<P>,
@@ -71,14 +106,14 @@ export function getRenderedComponent<P = any>(
   const _ComponentOrProps = ComponentOrProps as any
   const _DefaultComponent = DefaultComponent as any
 
-  if (TypeGuards.isNil(ComponentOrProps) || Object.keys(ComponentOrProps).length === 0) {
-    return null
-  }
-
   if (TypeGuards.isFunction(ComponentOrProps)) {
     return <_ComponentOrProps {...props as unknown as P} />
   }
 
+  if (TypeGuards.isNil(ComponentOrProps) || Object.keys(ComponentOrProps as object).length === 0) {
+    return null
+  }
+
   if (React.isValidElement(ComponentOrProps)) {
     return ComponentOrProps
   }
@@ -91,10 +126,10 @@ export function getRenderedComponent<P = any>(
 /**
  * Memoizes a React functional component to prevent unnecessary re-renders.
  *
- * This function wraps a React functional component using `React.memo`, which provides 
- * a mechanism for memoizing the result of rendering the component. By default, it 
+ * This function wraps a React functional component using `React.memo`, which provides
+ * a mechanism for memoizing the result of rendering the component. By default, it
  * uses a comparison function that always returns `true`, indicating that the component
- * should not re-render, regardless of prop changes. This behavior essentially freezes 
+ * should not re-render, regardless of prop changes. This behavior essentially freezes
  * the component's rendering until explicitly updated.
  *
  * @template P - The type of the component's props.
@@ -108,7 +143,7 @@ export function memoize<P extends object>(ComponentToMemoize: React.FunctionComp
 /**
  * Checks whether a specific property in two sets of props is equal.
  *
- * This function compares the value of a given property (`prop`) between two objects 
+ * This function compares the value of a given property (`prop`) between two objects
  * (`prevProps` and `nextProps`) using a deep equality check (`equals`).
  *
  * @template P - The type of the props object.
@@ -128,7 +163,7 @@ export function memoChecker<P>(prop: keyof P, prevProps: P, nextProps: P): boole
  * Memoizes a React functional component based on specific props.
  *
  * This function wraps a React functional component using `React.memo` with a custom comparison
- * function. The comparison function checks if the specified properties (passed as `check`) 
+ * function. The comparison function checks if the specified properties (passed as `check`)
  * remain equal between renders. If all specified properties are equal, the component will not re-render.
  *
  * @template P - The type of the component's props.
@@ -163,7 +198,7 @@ export function memoChecker<P>(prop: keyof P, prevProps: P, nextProps: P): boole
  */
 export function memoBy<P extends object>(
   ComponentToMemoize: React.FunctionComponent<P>,
-  check: keyof P | Array<keyof P>
+  check: keyof P | Array<keyof P>,
 ): React.NamedExoticComponent<P> {
   return React.memo(ComponentToMemoize, (prevProps, nextProps) => {
     const checks = Array.isArray(check) ? check : [check]

package/src/string.ts

@@ -1,27 +1,55 @@
+/** Collapses all newline characters in `text` to single spaces. */
 export function singleLine(text: string) {
   return text?.replace(/\n/g, ' ')
 }
 
-export function stringiparse(string) {
+/**
+ * Round-trips a value through `JSON.stringify` → `JSON.parse`.
+ *
+ * Strips non-serialisable properties (functions, `undefined`, class instances)
+ * and produces a plain-object clone. Throws if the value contains circular
+ * references.
+ */
+export function stringiparse(string: string) {
   return JSON.parse(JSON.stringify(string))
 }
 
+/**
+ * Changes only the first character of `str`.
+ *
+ * When `reverse` is `true` the first character is lowercased instead of
+ * uppercased — useful for converting PascalCase to camelCase.
+ */
 export function capitalize(str: string, reverse = false) {
   if (!str.length) return str
   const firstChar = reverse ? str[0].toLowerCase() : str[0].toUpperCase()
   return firstChar + str.substring(1)
 }
 
+/**
+ * Returns `true` if `char` is an uppercase Latin or extended Latin character.
+ *
+ * Covers the Unicode range `U+0080`–`U+024F` in addition to `A–Z`, so
+ * accented capitals (e.g. `É`, `Ñ`) are recognised correctly.
+ */
 export function isUppercase(char: string) {
   return /[A-Z]|[\u0080-\u024F]/.test(char) && char.toUpperCase() === char
 }
 
+/** Returns `true` when `char` is **not** considered uppercase by {@link isUppercase}. */
 export function isLowercase(char: string) {
   return !isUppercase(char)
 }
 
+/**
+ * Converts a camelCase or PascalCase identifier to a space-separated, title-cased string.
+ *
+ * A space is inserted before each uppercase letter that is immediately preceded
+ * by a lowercase letter. The first character is always uppercased.
+ * Consecutive uppercase runs (e.g. acronyms like "URL") are not split.
+ */
 export function humanizeCamelCase(str: string) {
-  const characters = []
+  const characters: string[] = []
   let previousCharacter = ''
   str.split('').forEach((char, idx) => {
     if (idx === 0) {
@@ -40,6 +68,13 @@ export function humanizeCamelCase(str: string) {
   return characters.join('')
 }
 
+/**
+ * Truncates `str` to `maxLen` characters, appending `'...'` when truncation occurs.
+ *
+ * The three dots count toward `maxLen`, so the returned string never exceeds
+ * `maxLen` characters when truncated. Strings already at or below `maxLen` are
+ * returned unchanged.
+ */
 export function ellipsis(str: string, maxLen: number) {
   if (str.length - 3 > maxLen) {
     return str.slice(0, maxLen - 3) + '...'

package/package.json.bak

@@ -1,31 +0,0 @@
-{
-  "name": "@codeleap/utils",
-  "version": "6.3.0",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/utils"
-  },
-  "devDependencies": {
-    "@codeleap/config": "workspace:*",
-    "@codeleap/types": "workspace:*",
-    "ts-node-dev": "1.1.8"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'"
-  },
-  "peerDependencies": {
-    "@codeleap/types": "workspace:*",
-    "axios": "^1.7.9",
-    "dayjs": "1.11.18",
-    "typescript": "5.5.2",
-    "react": "19.1.0",
-    "@tanstack/react-query": "5.89.0"
-  },
-  "dependencies": {
-    "tinycolor2": "^1.4.2",
-    "deep-equal": "^2.0.5"
-  }
-}