@matteodicristofalo/text-animations 1.0.0

package/.storybook/main.ts

@@ -0,0 +1,22 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  addons: [
+    "@storybook/addon-onboarding",
+    "@storybook/addon-essentials",
+    "@chromatic-com/storybook",
+    "@storybook/addon-interactions",
+  ],
+  framework: {
+    name: "@storybook/react-vite",
+    options: {},
+  },
+  viteFinal: async (config) => {
+    config.plugins?.push(tsconfigPaths());
+    return config;
+  },
+};
+
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,14 @@
+import type { Preview } from "@storybook/react";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

package/README.md

@@ -0,0 +1,138 @@
+# @mdc/text-animations
+
+This library provides a set of React components to animate text
+
+# Installation
+
+```bash
+npm install @mdc/text-animations
+# or
+yarn add @mdc/text-animations
+# or
+pnpm add @mdc/text-animations
+```
+
+# Usage
+
+The first thing to do in order to use this library is to import it's CSS.
+
+The following example is for a Next.js App but you can apply the same concept for different frameworks
+
+```js
+// app/layout.tsx
+
+...
+import "@mdc/text-animations/index.css";
+
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+Once imported the CSS you can use the React components.
+
+## SplitTextRevel
+
+```js
+"use client";
+
+import { SplitTextRevel } from "@mdc/text-animations";
+
+export function MyComponent() {
+  return (
+    <h1>
+      <SplitTextRevel text="Hello World" />
+    </h1>
+  );
+}
+```
+
+You can also choose how to split the text between one of this options:
+
+- char
+- word
+- sentence
+
+```js
+<SplitTextRevel text="Hello World" splitType="word" />
+```
+
+You can also configure the reveal animation by specifying:
+
+- duration
+- stagger
+
+```js
+"use client";
+
+import { useMemo } from "react";
+import { SplitTextRevel } from "@mdc/text-animations";
+
+export function MyComponent() {
+  const revealOptions = useMemo(
+    () => ({
+      duration: 1,
+      stagger: 0.5,
+    }),
+    []
+  );
+
+  return (
+    <h1>
+      <SplitTextRevel text="Hello World" revealOptions={revealOptions} />
+    </h1>
+  );
+}
+```
+
+## SplitTextRotate
+
+```js
+"use client";
+
+import { SplitTextRotate } from "@mdc/text-animations";
+
+export function MyComponent() {
+  return (
+    <h1>
+      <SplitTextRotate text="Hello World" />
+    </h1>
+  );
+}
+```
+
+Also here you can configure the aniimation
+
+```js
+"use client";
+
+import { useMemo } from "react";
+import { SplitTextRotate } from "@mdc/text-animations";
+
+export function MyComponent() {
+  const rotateOptions = useMemo(
+    () => ({
+      duration: 1,
+      stagger: 0.5,
+    }),
+    []
+  );
+
+  return (
+    <h1>
+      <SplitTextRotate text="Hello World" rotateOptions={rotateOptions} />
+    </h1>
+  );
+}
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@matteodicristofalo/text-animations",
+  "version": "1.0.0",
+  "description": "React library to animate text",
+  "scripts": {
+    "build": "rimraf dist && rollup -c",
+    "storybook": "storybook dev -p 6006"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^3.2.2",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-typescript": "^12.1.1",
+    "@storybook/addon-essentials": "^8.4.6",
+    "@storybook/addon-interactions": "^8.4.6",
+    "@storybook/addon-onboarding": "^8.4.6",
+    "@storybook/blocks": "^8.4.6",
+    "@storybook/react": "^8.4.6",
+    "@storybook/react-vite": "^8.4.6",
+    "@storybook/test": "^8.4.6",
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.28.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-postcss": "^4.0.2",
+    "sass": "^1.81.0",
+    "storybook": "^8.4.6",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "vite-tsconfig-paths": "^5.1.3"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./index.css": "./dist/index.css"
+  },
+  "author": "Matteo Di Cristofalo",
+  "license": "ISC",
+  "homepage": "https://github.com/matteodicristofalo/text-animations",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:matteodicristofalo/text-animations.git"
+  }
+}

package/rollup.config.mjs

@@ -0,0 +1,21 @@
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from '@rollup/plugin-typescript';
+import peerDepsExternal from 'rollup-plugin-peer-deps-external';
+import postCss from 'rollup-plugin-postcss';
+
+export default {
+  input: 'src/index.ts',
+  output: {
+    dir: 'dist',
+    format: 'es',
+  },
+  plugins: [
+    postCss({
+      extract: true,
+      modules: true,
+    }),
+    typescript(),
+    peerDepsExternal(),
+    resolve(),
+  ],
+}

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { SplitTextReveal } from "./split-text-reveal/split-text-reveal";
+export { SplitTextRotate } from "./split-text-rotate/split-text-rotate";

package/src/components/split-text-reveal/split-test-reveal.types.ts

@@ -0,0 +1,12 @@
+export type SplitTextRevealProps = {
+  text: string;
+  splitType?: SplitType;
+  revealOptions?: Partial<RevealOptions>;
+};
+
+type SplitType = "sentence" | "word" | "char";
+
+type RevealOptions = {
+  duration: number;
+  stagger: number;
+};

package/src/components/split-text-reveal/split-text-reveal.module.scss

@@ -0,0 +1,26 @@
+.text {
+  position: relative;
+
+  .container {
+    display: inline-flex;
+    overflow: hidden;
+
+    span {
+      min-width: 0.25em;
+      transform: translateY(100%);
+      transition-delay: var(--var-delay);
+      transition-duration: var(--var-duration);
+      transition-property: transform;
+      transition-timing-function: ease-out;
+      will-change: transform;
+    }
+  }
+
+  &.animate {
+    .container {
+      span {
+        transform: translateY(0);
+      }
+    }
+  }
+}

package/src/components/split-text-reveal/split-text-reveal.stories.ts

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { SplitTextReveal } from "./split-text-reveal";
+
+const meta = {
+  title: "SplitTextReveal",
+  component: SplitTextReveal,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    text: {
+      control: "text",
+    },
+    splitType: {
+      control: "radio",
+      options: ["char", "word", "sentence"],
+    },
+    revealOptions: {
+      control: {
+        type: "object",
+      },
+    },
+  },
+} satisfies Meta<typeof SplitTextReveal>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    text: "Here is the revealed text",
+    splitType: "char",
+  },
+};

package/src/components/split-text-reveal/split-text-reveal.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import React, { useMemo, useRef } from "react";
+import { round } from "@utils/numbers";
+import { characters, sentences, words } from "@utils/text";
+import { useIntersectionObserver } from "@hooks";
+import { SplitTextRevealProps } from "./split-test-reveal.types";
+import clsx from "clsx";
+import styles from "./split-text-reveal.module.scss";
+
+const DEFAULT_DURATION = 0.5;
+const DEFAULT_STAGGER = 0.01;
+
+export function SplitTextReveal({
+  text,
+  splitType = "char",
+  revealOptions,
+}: SplitTextRevealProps) {
+  const ref = useRef(null);
+  const memoizedOptions = useMemo(() => ({ once: true, threshold: 0.1 }), []);
+  const isInView = useIntersectionObserver(ref, memoizedOptions);
+  const transitionDuration = revealOptions?.duration || DEFAULT_DURATION;
+  const transitionStagger = revealOptions?.stagger || DEFAULT_STAGGER;
+
+  const splitFn = useMemo(() => {
+    switch (splitType) {
+      case "sentence":
+        return sentences;
+      case "word":
+        return words;
+      case "char":
+        return characters;
+    }
+  }, [splitType]);
+
+  return (
+    <span
+      ref={ref}
+      className={clsx(styles["text"], { [styles["animate"]]: isInView })}
+      style={
+        {
+          "--var-duration": `${transitionDuration}s`,
+        } as React.CSSProperties
+      }
+    >
+      {splitFn(text).map((el, i) => (
+        <span key={i} className={styles["container"]}>
+          <span
+            style={
+              {
+                "--var-delay": `${round(transitionStagger * i, 3)}s`,
+              } as React.CSSProperties
+            }
+          >
+            {el}
+          </span>
+        </span>
+      ))}
+    </span>
+  );
+}

package/src/components/split-text-rotate/split-text-rotate.module.scss

@@ -0,0 +1,34 @@
+.text {
+  display: block;
+  overflow: hidden;
+  position: relative;
+
+  .container {
+    display: flex;
+
+    &:nth-of-type(2) {
+      position: absolute;
+      top: 0;
+      transform: translateY(100%);
+    }
+
+    .char {
+      display: inline-block;
+      min-width: 0.25em;
+      transition-delay: var(--var-delay-out);
+      transition-duration: var(--var-duration);
+      transition-property: transform;
+      transition-timing-function: ease-out;
+      will-change: transform;
+    }
+  }
+
+  &:hover {
+    .container {
+      .char {
+        transform: translateY(-100%);
+        transition-delay: var(--var-delay-in);
+      }
+    }
+  }
+}

package/src/components/split-text-rotate/split-text-rotate.stories.ts

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { SplitTextRotate } from "./split-text-rotate";
+
+const meta = {
+  title: "SplitTextRotate",
+  component: SplitTextRotate,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    text: {
+      control: "text",
+    },
+    rotateOptions: {
+      control: {
+        type: "object",
+      },
+    },
+  },
+} satisfies Meta<typeof SplitTextRotate>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    text: "Rotating text",
+  },
+};

package/src/components/split-text-rotate/split-text-rotate.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import React, { useCallback } from "react";
+import { round } from "@utils/numbers";
+import { characters } from "@utils/text";
+import { SplitTextRotateProps } from "./split-text-rotate.types";
+import styles from "./split-text-rotate.module.scss";
+
+const DEFAULT_DURATION = 0.25;
+const DEFAULT_STAGGER = 0.025;
+
+export function SplitTextRotate({ text, rotateOptions }: SplitTextRotateProps) {
+  const transitionDuration = rotateOptions?.duration || DEFAULT_DURATION;
+  const transitionStagger = rotateOptions?.stagger || DEFAULT_STAGGER;
+  const splittedText = characters(text);
+
+  const delays = useCallback(
+    (index: number) => {
+      const noElementsZeroBased = splittedText.length - 1;
+      return {
+        in: round(transitionStagger * index, 3),
+        out: round(transitionStagger * (noElementsZeroBased - index), 3),
+      };
+    },
+    [splittedText, transitionStagger]
+  );
+
+  return (
+    <span
+      className={styles["text"]}
+      style={
+        {
+          "--var-duration": `${transitionDuration}s`,
+        } as React.CSSProperties
+      }
+    >
+      {Array.from({ length: 2 }).map((_, i) => (
+        <span key={i} className={styles["container"]}>
+          {splittedText.map((char, i) => {
+            const charDelays = delays(i);
+            return (
+              <span
+                key={i}
+                className={styles["char"]}
+                style={
+                  {
+                    "--var-delay-in": `${charDelays.in}s`,
+                    "--var-delay-out": `${charDelays.out}s`,
+                  } as React.CSSProperties
+                }
+              >
+                {char}
+              </span>
+            );
+          })}
+        </span>
+      ))}
+    </span>
+  );
+}

package/src/components/split-text-rotate/split-text-rotate.types.ts

@@ -0,0 +1,9 @@
+export type SplitTextRotateProps = {
+  text: string;
+  rotateOptions?: Partial<RotateOptions>;
+};
+
+type RotateOptions = {
+  duration: number;
+  stagger: number;
+};

package/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module "*.module.scss" {
+  const classes: { [key: string]: string };
+  export default classes;
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useIntersectionObserver } from "./intersection-overser/intersection-observer";

package/src/hooks/intersection-overser/intersection-observer.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useEffect, useState, RefObject } from "react";
+
+type Options = IntersectionObserverInit & {
+  once?: boolean;
+};
+
+export function useIntersectionObserver(
+  ref: RefObject<HTMLElement>,
+  options?: Options
+): boolean {
+  const [isIntersecting, setIntersecting] = useState(false);
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (options?.once) {
+          if (entry.isIntersecting) {
+            setIntersecting(true);
+            observer.disconnect();
+          }
+        } else {
+          setIntersecting(entry.isIntersecting);
+        }
+      },
+      {
+        threshold: 0.75,
+        ...options,
+      }
+    );
+
+    observer.observe(ref.current);
+
+    return () => observer.disconnect();
+  }, [ref, options]);
+
+  return isIntersecting;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./components";

package/src/utils/numbers.ts

@@ -0,0 +1,3 @@
+export function round(num: number, digits: number): number {
+  return parseFloat(num.toFixed(digits));
+}

package/src/utils/text.ts

@@ -0,0 +1,19 @@
+export function sentences(text: string) {
+  return segment(text, "sentence");
+}
+
+export function words(text: string) {
+  return segment(text, "word");
+}
+
+export function characters(text: string) {
+  return segment(text, "grapheme");
+}
+
+export function segment(
+  text: string,
+  granularity: "sentence" | "word" | "grapheme"
+) {
+  const segmenter = new Intl.Segmenter(undefined, { granularity });
+  return Array.from(segmenter.segment(text), (segment) => segment.segment);
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "esModuleInterop": true,
+    "jsx": "react",
+    "lib": ["esnext", "dom"],
+    "outDir": "dist",
+    "paths": {
+      "@hooks": ["./src/hooks/index"],
+      "@utils/*": ["./src/utils/*"]
+    }
+  }
+}