wip(#7): add more text transformation functions and tests

close #8, close #9, close #10, close #11, close #12

Author: khatastroffik

package.json

@@ -14,7 +14,7 @@
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "lint:inspect": "eslint --inspect-config",
-    "check": "tsc --noEmit src/index.ts --jsx react-jsx --esModuleInterop --skipLibCheck",
+    "check": "tsc --noEmit src/index.ts --jsx react-jsx --esModuleInterop --skipLibCheck --lib esnext" ,
     "test": "jest",
     "test:watch": "jest --watch --verbose",
     "test:ci": "jest --ci --noStackTrace --passWithNoTests -c jest.config.ci.ts",

src/components/TextRenderer/TextRenderer.mdx

@@ -20,7 +20,26 @@ The text representation can be customized using the appropriates tag attributes
 
 Notes:
 
-- This component is rendering text transformed by predefined, standard functions like "lowercase", "uppercase", "camelcase", "kebabcase" etc. 
+- This component is rendering text transformed by predefined, standard `transform` functions:
+    - **no-op**: the text is rendered as-is (_no operation_)
+    - **lower-case**: use the standard `toLowerCase()` string transformation for rendition.
+    - **upper-case**: use the standard `toUpperCase()` string transformation for rendition.
+    - **camel-case**: starts by making the first word lowercase. Then, it capitalizes the first letter of each word that follows. Then It removes the non-letter chars from the text.  
+    `My name is Nobody` → `myNameIsNobody`.
+    - **pascal-case**: capitalizes the first letter of each word. Then It removes the non-letter chars from the text.  
+    `My name is Nobody` → `MyNameIsNobody`.
+    - **snake-case**: separates each word with an underscore character (`_`). The rendered result is lowercased.  
+    `My name is Nobody` → `my_name_is_nobody`.
+    - **kebab-case**: separates each word with a dash character (`-`). The rendered result is lowercased.  
+    `My name is Nobody` → `my-name-is-nobody`.
+    - **to-base64**: renders a valid UTF-16 string to it's Base64 encoded representation.  
+    `Hello there! Ā 文 🦄 ❤️` → `SGVsbG8gdGhlcmUhIMSAIOaWhyDwn6aEIOKdpO+4jw==`  
+    ⚠ this may throw an Error if the input value is not a valid UTF-16 string. ⚠
+    - **from-base64**: renders a valid Base64 string into it's UTF-16 decoded string representation.  
+     `SGVsbG8gdGhlcmUhIMSAIOaWhyDwn6aEIOKdpO+4jw==` → `Hello there! Ā 文 🦄 ❤️`  
+     ⚠ this may throw an Error if the input value is not a valid Base64 string. ⚠
+    - **camel-to-kebab**: renders a camel-cased string into it's kebab-case representation.
+    - **pascal-to-kebab**: renders a pascal-cased string into it's kebab-case representation.
 - The values and options used/available within the "Control" column are for demonstration purpose only.
 - Use the "Reset controls" button on the top right side of the table in order to restore the initial demo values and options. Alternatively, you could reload the page.
 
@@ -30,7 +49,7 @@ Notes:
 import { TextRenderer } from 'react-text-renderer-components';
 
 const Example = () => {
-    return <TextRenderer value={"SOME TEXT"} transform="lowercase" />
+    return <TextRenderer value={"SOME TEXT"} transform="lower-case" />
 }`
 } />
 

src/components/TextRenderer/TextRenderer.spec.tsx

@@ -2,65 +2,175 @@ import React from "react";
 import { render } from '@testing-library/react';
 import { TextRenderer } from "./TextRenderer";
 
+// FIX "[ReferenceError: TextEncoder is not defined]" for Base64 transformations (see: https://stackoverflow.com/a/68468204)
+import { TextEncoder, TextDecoder } from 'util';
+Object.assign(global, { TextDecoder, TextEncoder });
+
+const INVALID_CHARACTER_ERROR = "InvalidCharacterError";
+const INVALID_UTF16_ERROR_MSG = "The input value is not well formed: it is not a valid UTF-16 string, since it contains lone surrogates.";
+const INVALID_BASE64_ERROR_MSG = "The input value is not a valid BASE64 string and cannot be decoded.";
+
+
 describe("TextRenderer component", () => {
 
-    it("should render a text value to lowercase", () => {
+    it("should render a 'spanned', lowercased text", () => {
         const sourceText = "SOURCE TEXT";
-        const r = render(<TextRenderer value={sourceText} transform="lowercase" pure />);
-        expect(r.container.innerHTML).toEqual(sourceText.toLowerCase());
+        const r = render(<TextRenderer value={sourceText} transform="lower-case" />);
+        expect(r.container.innerHTML).toEqual(`<span>${sourceText.toLowerCase()}</span>`);
+    });
+
+    it("should render an empty text when value is undefined or null", () => {
+        const sourceTextUndefined = undefined;
+        const sourceTextNull = null;
+        expect.assertions(2);
+        const r1 = render(<TextRenderer value={sourceTextUndefined} transform="upper-case" pure />);
+        expect(r1.container.innerHTML).toEqual("");
+        const r2 = render(<TextRenderer value={sourceTextNull} transform="upper-case" pure />);
+        expect(r2.container.innerHTML).toEqual("");
+    });
+
+    it("should render an umodified text value when transformation is invalid", () => {
+        const sourceText = "I shall NOT be modified";
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const invalidTransformation: any = "I'm an invalid transformation";
+        const r = render(<TextRenderer value={sourceText} transform={invalidTransformation} pure />);
+        expect(r.container.innerHTML).toEqual(sourceText);
+    });
+
+    it("should render an umodified text value when transformation is not defined or null", () => {
+        const sourceText = "I shall NOT be modified";
+        const invalidTransformationNull = null;
+        const invalidTransformationUndefined = undefined;
+        expect.assertions(4);
+        const r1 = render(<TextRenderer value={sourceText} transform={invalidTransformationNull} pure />);
+        expect(r1.container.innerHTML).toEqual(sourceText);
+        const r2 = render(<TextRenderer value={sourceText} transform={invalidTransformationUndefined} pure />);
+        expect(r2.container.innerHTML).toEqual(sourceText);
+        const r3 = render(<TextRenderer value={sourceText} transform={null} pure />);
+        expect(r3.container.innerHTML).toEqual(sourceText);
+        const r4 = render(<TextRenderer value={sourceText} transform={undefined} pure />);
+        expect(r4.container.innerHTML).toEqual(sourceText);
+    });
+
+    it("protected method 'getFormatedText()' should return a string", () => {
+        const sourceText = "SOURCE text";
+        class TextRendererWrapper extends TextRenderer {
+            public getFormatedText() {
+                return super.getFormatedText();
+            }
+        }
+        const component = new TextRendererWrapper({ value: sourceText, transform: "lower-case" });
+        expect(component.getFormatedText()).toEqual(sourceText.toLowerCase());
+    });
+
+});
+describe("TextRenderer transformation", () => {
+
+    it("should render an umodified text value when transformation is 'no-op' (no-operation)", () => {
+        const sourceText = "I shall NOT be modified";
+        const r = render(<TextRenderer value={sourceText} transform="no-op" pure />);
+        expect(r.container.innerHTML).toEqual(sourceText);
     });
 
-    it("should render a spanned, lowercased text", () => {
+    it("should render a text value to lowercase", () => {
         const sourceText = "SOURCE TEXT";
-        const r = render(<TextRenderer value={sourceText} transform="lowercase" />);
-        expect(r.container.innerHTML).toEqual(`<span>${sourceText.toLowerCase()}</span>`);
+        const r = render(<TextRenderer value={sourceText} transform="lower-case" pure />);
+        expect(r.container.innerHTML).toEqual(sourceText.toLowerCase());
     });
 
     it("should render a text value to uppercase", () => {
         const sourceText = "source text";
-        const r = render(<TextRenderer value={sourceText} transform="uppercase" pure />);
+        const r = render(<TextRenderer value={sourceText} transform="upper-case" pure />);
         expect(r.container.innerHTML).toEqual(sourceText.toUpperCase());
     });
 
-    it("should render an empty text when value is undefined", () => {
-        const sourceText = undefined;
-        const r = render(<TextRenderer value={sourceText} transform="noop" pure />);
-        expect(r.container.innerHTML).toEqual("");
+    it("should render a text value to camel-case", () => {
+        const sourceText = "I Think Ruth's Dog maXIMUM is cuter than your-dog_John23!";
+        const expected = "iThinkRuthSDogMaximumIsCuterThanYourDogJohn23";
+        const r = render(<TextRenderer value={sourceText} transform="camel-case" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
     });
 
-    it("should render an empty text when value is null", () => {
-        const sourceText = null;
-        const r = render(<TextRenderer value={sourceText} transform="noop" pure />);
-        expect(r.container.innerHTML).toEqual("");
+    it("should render a text value to pascal-case", () => {
+        const sourceText = "I Think Ruth's Dog maXIMUM is cuter than your-dog_John23!";
+        const expected = "IThinkRuthSDogMaximumIsCuterThanYourDogJohn23";
+        const r = render(<TextRenderer value={sourceText} transform="pascal-case" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
     });
 
-    it("should render an umodified text value when transformation is 'noop' (no-operation)", () => {
-        const sourceText = "SOURCE text";
-        const r = render(<TextRenderer value={sourceText} transform="noop" pure />);
-        expect(r.container.innerHTML).toEqual(sourceText);
+    it("should render a text value to kebab-case", () => {
+        const sourceText = "I Think Ruth's Dog maXIMUM is cuter than your-dog_John23!";
+        const expected = "i-think-ruth-s-dog-maximum-is-cuter-than-your-dog-john23";
+        const r = render(<TextRenderer value={sourceText} transform="kebab-case" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
     });
 
-    it("should render an umodified text value when transformation is null", () => {
-        const sourceText = null;
-        const r = render(<TextRenderer value={sourceText} transform={null} pure />);
-        expect(r.container.innerHTML).toEqual("");
+    it("should render a text value to snake-case", () => {
+        const sourceText = "I Think Ruth's Dog maXIMUM is cuter than your-dog_John23!";
+        const expected = "I_Think_Ruth_s_Dog_maXIMUM_is_cuter_than_your_dog_John23";
+        const r = render(<TextRenderer value={sourceText} transform="snake-case" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
     });
 
-    it("should render an umodified text value when transformation is undefined", () => {
-        const sourceText = null;
-        const r = render(<TextRenderer value={sourceText} transform={undefined} pure />);
-        expect(r.container.innerHTML).toEqual("");
+    it("should render a text value in camel-case to kebab-case", () => {
+        const sourceText = "iThinkRuthSDogMaximumIsCuterThanYourDogJohn23";
+        const expected = "i-think-ruth-s-dog-maximum-is-cuter-than-your-dog-john23";
+        const r = render(<TextRenderer value={sourceText} transform="camel-to-kebab" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
     });
 
-    it("protected method 'getFormatedText()' should return a string", () => {
-        const sourceText = "SOURCE text";
-        class TextRendererWrapper extends TextRenderer {
-            public getFormatedText() {
-                return super.getFormatedText();
-            }
+    it("should render a text value in pascal-case to kebab-case", () => {
+        const sourceText = "IThinkRuthSDogMaximumIsCuterThanYourDogJohn23";
+        const expected = "i-think-ruth-s-dog-maximum-is-cuter-than-your-dog-john23";
+        const r = render(<TextRenderer value={sourceText} transform="pascal-to-kebab" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
+    });
+
+    it("should decode a Base64 string value to a UTF-16 string", () => {
+        const sourceText = "YSDEgCDwkICAIOaWhyDwn6aE";
+        const expected = "a Ā 𐀀 文 🦄";
+        const r = render(<TextRenderer value={sourceText} transform="from-base64" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
+    });
+
+    it("should encode an UTF-16 text value to a Base64 string", () => {
+        const sourceText = "a Ā 𐀀 文 🦄";
+        const expected = "YSDEgCDwkICAIOaWhyDwn6aE";
+        const r = render(<TextRenderer value={sourceText} transform="to-base64" pure />);
+        expect(r.container.innerHTML).toEqual(expected);
+    });
+
+    it("should throw when attempting to encode an invalid UTF-16 text value to a Base64 string", () => {
+        const invalidSourceText = "hello⛳❤️🧀\uDE75";
+        const spy = jest.spyOn(console, 'error');
+        spy.mockImplementation(() => { });
+
+        expect.assertions(3);
+        try {
+            render(<TextRenderer value={invalidSourceText} transform="to-base64" pure />);
+        } catch (error) {
+            expect(error).toBeInstanceOf(DOMException);
+            expect(error).toHaveProperty('message', INVALID_UTF16_ERROR_MSG);
+            expect(error).toHaveProperty('name', INVALID_CHARACTER_ERROR);
+        }
+        spy.mockRestore();
+    });
+
+    it("should throw when attempting to decode an invalid Base64 text value to a UTF-16 string", () => {
+        const invalidSourceText = "BANZAI!";
+        const spy = jest.spyOn(console, 'error');
+        spy.mockImplementation(() => { });
+
+        expect.assertions(3);
+        try {
+            render(<TextRenderer value={invalidSourceText} transform="from-base64" pure />);
+        } catch (error) {
+            expect(error).toBeInstanceOf(DOMException);
+            expect(error).toHaveProperty('message', INVALID_BASE64_ERROR_MSG);
+            expect(error).toHaveProperty('name', INVALID_CHARACTER_ERROR);
         }
-        const component = new TextRendererWrapper({ value: sourceText, transform: "noop" });
-        expect(component.getFormatedText()).toEqual(sourceText);
+        spy.mockRestore();
     });
 
+
 });

src/components/TextRenderer/TextRenderer.stories.tsx

@@ -1,58 +1,103 @@
-import React from 'react';
+import React, { Component, ReactNode } from "react";
+import { useArgs } from '@storybook/preview-api';
 import { Meta, StoryObj } from '@storybook/react';
-import { TextRenderer } from './TextRenderer';
+import { ITextRendererProps, TextRenderer, TextTransformations } from './TextRenderer';
 import { RemoveKeyAttribute } from "../../../.storybook/utils";
 
-const testtext = "some text";
+const testtext = "fancy-TEXT with_Unicode CharPoints Ā𐀀文🦄";
+// BASE64 = ZmFuY3ktVEVYVCB3aXRoX1VuaWNvZGUgQ2hhclBvaW50cyDEgPCQgIDmlofwn6aE
 
 // +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 const meta = {
-  title: 'Components/TextRenderer',
-  component: TextRenderer,
-  argTypes: {
-    value: {
-      control: "text",
-      description: "The text **value** (string) which should be transformed and rendered.",
+    title: 'Components/TextRenderer',
+    component: TextRenderer,
+    argTypes: {
+        value: {
+            control: "text",
+            description: "The text **value** (string) which should be transformed and rendered.",
+        },
+        pure: {
+            control: "boolean",
+            description: "If **pure** is set/defined, then the component will render nothing but the 'pure' text representation of the value. Otherwise, the text representation is embeded within a *<span></span>* tag.",
+        },
+        transform: {
+            control: "select",
+            description: "The type of transformation to be applied to the input values.",
+            options: TextTransformations,
+        }
     },
-    pure: {
-      control: "boolean",
-      description: "If **pure** is set/defined, then the component will render nothing but the 'pure' text representation of the value. Otherwise, the text representation is embeded within a *<span></span>* tag.",
+    parameters: {
+        docs: {
+            controls: { sort: "requiredFirst" },
+            source: { language: 'tsx', type: 'auto', transform: RemoveKeyAttribute },
+            description: { component: "The **TextRenderer** component renders an input *value* of type `string` to a pure/spanned representation showing the transformed text as defined by the `transform` attribute of the component." },
+        },
+        layout: 'centered'
     },
-    transform: {
-      control: "select",
-      description: "The type of transformation to be applied to the input values.",
-      options: ["noop", "lowercase", "uppercase"],
-    }
-  },
-  parameters: {
-    docs: {
-      controls: { sort: "requiredFirst" },
-      source: { language: 'tsx', type: 'auto', transform: RemoveKeyAttribute },
-      description: { component: "The **TextRenderer** component renders an input *value* of type `string` to a pure/spanned representation showing the transformed text as defined by the `transform` attribute of the component." },
-    },
-    layout: 'centered'
-  },
-  render: RenderTextRenderer
+    render: RenderTextRenderer
 } satisfies Meta<typeof TextRenderer>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
 // +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-function RenderTextRenderer(args) {
-  return <TextRenderer key={Math.random()} {...args} />
+interface ErrorBoundaryProps { children?: ReactNode; fallback: () => void; }
+interface ErrorState { hasError: boolean; error?: Error; }
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorState> {
+
+    state: ErrorState = { hasError: false, error: null };
+
+    constructor(props) {
+        super(props);
+    }
+
+    static getDerivedStateFromError(error: Error): ErrorState {
+        return { hasError: true, error };
+    }
+
+    componentDidCatch(error: Error) {
+        console.error(`[CAPTURED] ${error.name}: ${error.message}`);
+    }
+
+    render() {
+        if (this.state.hasError) {
+            return (<>
+                <style>{`.errordisplay { padding: 15px; text-align: center; }`}</style>
+                <div className='errordisplay' >
+                    <h2>{this.state.error.name ?? "UNKNOWN ERROR"}</h2>
+                    <h3>{this.state.error.message ?? "(no description available)"}</h3>
+                    <button onClick={() => this.props.fallback()}>reload this component</button>
+                </div>
+            </>);
+        } else {
+            return this.props.children;
+        }
+    }
+}
+
+function RenderTextRenderer(args: ITextRendererProps) {
+    const [, , resetArgs] = useArgs<ITextRendererProps>();
+    const key = Math.random();
+    return (
+        <ErrorBoundary key={key} fallback={resetArgs}>
+            <TextRenderer key={key} {...args} />
+        </ErrorBoundary>
+    );
 }
 
+
+
 // +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 export const Playground = {
-  name: "Playground",
-  args: {
-    value: testtext,
-    pure: true,
-    transform: "noop"
-  },
-  tags: ['!dev']
+    name: "Playground",
+    args: {
+        value: testtext,
+        pure: true,
+        transform: "no-op"
+    },
+    tags: ['!dev']
 } satisfies Story;