From 95754b61aca7f025834909f7073a106f3a30a683 Mon Sep 17 00:00:00 2001 From: Amer-Jabar Date: Thu, 17 Oct 2024 11:48:12 +0200 Subject: [PATCH] KH-9 Update documentation and rename animation duration parameters --- .DS_Store | Bin 6148 -> 6148 bytes README.md | 115 +++++++++++++++++++++++++++++++++++---------------- khoshnus.js | 18 ++++---- package.json | 2 +- 4 files changed, 90 insertions(+), 45 deletions(-) diff --git a/.DS_Store b/.DS_Store index 7e535bd00411b3bf80ed28c69ed58481f9112d18..bb3ee9036b43ed00839811e1cef8a7f66914501c 100644 GIT binary patch delta 53 zcmZoMXfc@JFUrZlz`)4BAi%(o!H~yL%23Rp$B?yIkYhPBBj;uZmIsWRgV?q*PHafq J%+B$b9{?(J4J!Zu delta 131 zcmZoMXfc@JFUrlpz`)4BAi%&-!Jx;G!BE1G%aF5KkYhQsDM*ToA(J7GA%!6oS=uuv zKRGEUKM5!g)W_fe#1{X-fPrB%56c5a&SZunpvD4*lF14zB76+%fhzRiDxR|LVcg8l H@s}R}fwCjs diff --git a/README.md b/README.md index cecabb1..54f65fa 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # ✨ Khoshnus - Craft Beautiful Handwritten SVG Text Animations -Khoshnus is just a library, but it's also your tool for bringing life to static text in an artistic way. With its elegant SVG animations, your text can now be revealed as if written by hand! + +Khoshnus is just a library, but it's also your tool for bringing life to static text in an artistic way. With its +elegant SVG animations, your text can now be revealed as if written by hand! ## 🖋️ What Does Khoshnus Do? @@ -19,64 +21,120 @@ Khoshnus lets you: ## 🚀 Quick Start -Here's how you can make your text come alive with Khoshnus: + +### 📦 Installation + +To get started with Khoshnus, add the npm package to your project by running either of the following commands: + +```bash +npm install khoshnus +-------------------- +yarn add khoshnus +``` + +### TL;DR + +Do this if you are using React. +```javascript +import { FONT_MATRIX, initialize, write } from "khoshnus" +import 'khoshnus/style.css' + +const App = () => { + useEffect(() => { + initialize({ + font: FONT_MATRIX['Pinyon Script'].name, + fontSize: "8px", + }); + write("Hello Universe, My Name Is Optimus Prime!"); + }, []); + + return ( +
+ +
+ ) +} +``` + +--- + +--- ### 1. Include the SVG in Your HTML -Add an empty SVG element with an id that Khoshnus will use to animate your text: +Add an empty SVG element with the id of `khoshnus` that Khoshnus will use to animate your text. Feel free to adjust the size of the SVG +based on your needs. ```html + ``` ### 2. Initialize and Write Your Text -Once the page is ready, use Khoshnus to initialize the animation and define the text you want to animate: +Once you have your bare HTML file, import the basic stuff needed from the library: + +```javascript +import { initialize, write, FONT_MATRIX } from "khoshnus"; + +import "khoshnus/style.css"; +``` + +Then start using the library: ```javascript +// Initialize the global configuration. initialize({ - font: FONT_MATRIX["Parisienne"].name, // Any of the available fonts. - fontSize: "10px", // Any font size suitable for your SVG element. + font: FONT_MATRIX["Parisienne"].name, // Any of the supported fonts. + fontSize: "10px", // Any font size suitable for your SVG element bounds. }); +// Write the letters into the SVG element. write("Hello Universe, My Name Is Optimus Prime!"); ``` ### 3. Customize Your Animation -Khoshnus offers full control over your animation. Want the text to feel like it’s written slowly or quickly? You decide! Here’s a glimpse of how you can tweak it: + +Khoshnus offers full control over your animation. Want the text to feel like it’s written slowly or quickly? You decide! +Here’s a glimpse of how you can tweak it: ```javascript initialize({ - font: FONT_MATRIX["Pinyon Script"].name, - fontSize: "12px", - startStrokeDashoffset: 100, - startStrokeWidth: 0.01, + font: FONT_MATRIX["Pinyon Script"].name, // Only fonts from FONT_MATRIX are available. + fontSize: "16px", + startStrokeDashoffset: FONT_MATRIX["Pinyon Script"].strokeDashoffset, // Or any strokeDashoffset you want the letters to start with. + startStrokeWidth: 0.001, + startFill: "transparent", endFill: "black", startStroke: "black", endStrokeDashoffset: 0, - endStrokeWidth: 0.1, + endStrokeWidth: 0.3, + endStroke: "transparent", baseAnimationDelay: 2.5, textFillExtraAnimationDelay: 3, }); ``` -### You can define: - -- Font and Size: Choose from several beautiful fonts with distinct styles. -- Stroke and Fill: Customize how each letter is drawn and filled. -- Animation Delays: Fine-tune the speed and sequence of how letters appear on the screen. ### ✍️ Make Every Letter Special + The magic of Khoshnus lies in its ability to animate text letter-by-letter. Here’s an example: ```javascript write("Your Text Here", { letterConfiguration: { delay: 0.25, // Delays each letter's animation + }, + textConfiguration: { + x: "50%", // X position of the text. + y: "50%", // Y position of the text. + textAnchor: "middle", // Anchor of the text. + dominantBaseline: "middle", // Baseline of the text - where it should align. + fontSize: "12px" // Font size - appearance could possibly depend on the parent element. } }); ``` -With `letterConfiguration`, you control how fast each letter appears, giving your text an artistic, flowing motion. ### 🖼️ Font Options + Here are some of the unique fonts you can play with: - **BlackCherry**: Bold strokes with an offset of 80 @@ -89,23 +147,8 @@ Here are some of the unique fonts you can play with: - **Sevillana**: Spanish-inspired curves, with an offset of 120 - **Pinyon Script**: Formal and sophisticated, offset of 100 -## 📦 Installation -To get started with Khoshnus, simply clone or download the project and link the JavaScript file to your page: - -### Add the dependency to your project: -```bash -npm install khoshnus -yarn add khoshnus -``` -### Import the dependency: - -```javascript -const { initialize, write } = require("khoshnus"); -``` - -### ✨ Start using it! - ### 🌟 Creative Use Cases + Here are just a few ways you can use Khoshnus: - Display personalized signature animations for your website. @@ -114,5 +157,7 @@ Here are just a few ways you can use Khoshnus: - Create a storybook-like experience with flowing, hand-drawn text. ### ⚖️ License -This project is licensed under the MIT License, meaning you're free to use, modify, and distribute it in both personal and commercial projects. + +This project is licensed under the MIT License, meaning you're free to use, modify, and distribute it in both personal +and commercial projects. diff --git a/khoshnus.js b/khoshnus.js index ea10736..6570481 100644 --- a/khoshnus.js +++ b/khoshnus.js @@ -4,7 +4,7 @@ const checkConfigurationValidity = (predicate, configuration) => { if (!predicate(configuration)) throw new Error(INCORRECT_CONFIGURATION_PROVIDED_ERROR_MESSAGE); } -const FONT_MATRIX = { +export const FONT_MATRIX = { "BlackCherry": { name: "BlackCherry", strokeDashoffset: 80 @@ -43,13 +43,13 @@ const FONT_MATRIX = { }, } -const initSvgStyle = ({ font, fontSize, startStrokeDashoffset, startStrokeWidth, startFill, startStroke, baseAnimationDelay, textFillExtraAnimationDelay }) => { +const initSvgStyle = ({ font, fontSize, startStrokeDashoffset, startStrokeWidth, startFill, startStroke, baseAnimationDuration, textFillExtraAnimationDuration }) => { if (!FONT_MATRIX[font]) throw new Error("Font is not supported.") const fontStyle = ` #${KHOSHNUS_SVG_ID} text tspan { stroke-dasharray: ${startStrokeDashoffset || FONT_MATRIX[font].startStrokeDashoffset}; stroke-dashoffset: ${startStrokeDashoffset || FONT_MATRIX[font].startStrokeDashoffset}; - animation: draw-stroke ${baseAnimationDelay}s cubic-bezier(0.215, 0.610, 0.355, 1) forwards, draw-fill ${textFillExtraAnimationDelay}s cubic-bezier(0.5, 0.135, 0.15, 0.56) forwards; + animation: draw-stroke ${baseAnimationDuration}s cubic-bezier(0.215, 0.610, 0.355, 1) forwards, draw-fill ${textFillExtraAnimationDuration}s cubic-bezier(0.5, 0.135, 0.15, 0.56) forwards; stroke: ${startStroke}; stroke-width: ${startStrokeWidth}; fill: ${startFill}; @@ -58,7 +58,7 @@ const initSvgStyle = ({ font, fontSize, startStrokeDashoffset, startStrokeWidth, } ` - var style = document.createElement("style"); + const style = document.createElement("style"); style.innerHTML = fontStyle; document.getElementsByTagName('head')[0].appendChild(style); } @@ -80,13 +80,13 @@ const initializeKeyframesCss = ({ endStrokeDashoffset, endStrokeWidth, endFill, ` const initializeKeyframes = (initializationConfiguration) => { - var style = document.querySelector("style"); + const style = document.querySelector("style"); style.innerHTML = style.innerHTML.concat(initializeKeyframesCss(initializationConfiguration)); } /** - * baseAnimationDelay - the delay of the strokes animation. - * textFillExtraAnimationDelay - the delay of the text fillings animation. It is adviced to have this equal to or more than baseAnimationDelay. + * baseAnimationDuration - the duration of strokes animation. This controls how fast does it take for the edges to animate. + * textFillExtraAnimationDuration - the duration of the text fillings animation. It is advised to have this equal to or more than baseAnimationDuration. */ const defaultInitializationConfiguration = { font: FONT_MATRIX["Pinyon Script"].name, @@ -99,8 +99,8 @@ const defaultInitializationConfiguration = { endStrokeDashoffset: 0, endStrokeWidth: 0.3, endStroke: "transparent", - baseAnimationDelay: 2.5, - textFillExtraAnimationDelay: 3, + baseAnimationDuration: 2.5, + textFillExtraAnimationDuration: 3, } const initialize = (initializationConfiguration = defaultInitializationConfiguration) => { diff --git a/package.json b/package.json index e559277..fccd372 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "khoshnus", - "version": "1.0.0", + "version": "1.0.3", "description": "A library to write text in a nice (calligraphy) animated fashion", "main": "khoshnus.js", "scripts": {