@e1011/es-kit 1.2.1 → 1.2.4

package/README.md

@@ -1,48 +1,193 @@
-<h1 align="center">Welcome to @e1011/es-kit 👋</h1>
-<p>
-  <a href="https://www.npmjs.com/package/@e1011/es-kit" target="_blank">
-    <img alt="Version" src="https://img.shields.io/npm/v/@e1011/es-kit.svg">
-  </a>
-  <a href="https://github.com/edgar0011/e1011-es-kit#readme" target="_blank">
-    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
-  </a>
-  <a href="https://github.com/edgar0011/e1011-es-kit/graphs/commit-activity" target="_blank">
-    <img alt="Maintenance" src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" />
-  </a>
-  <a href="https://github.com/edgar0011/e1011-es-kit/blob/master/LICENSE" target="_blank">
-    <img alt="License: MIT" src="https://img.shields.io/github/license/edgar0011/@e1011/es-kit" />
-  </a>
-</p>
-
-> UI, Utils, Hooks, Helpers for VanillaJS and React based apps
-
-## Install
+# @e1011/es-kit
+
+[![npm version](https://img.shields.io/npm/v/@e1011/es-kit.svg)](https://www.npmjs.com/package/@e1011/es-kit)
+[![License: MIT](https://img.shields.io/github/license/edgar0011/e1011-es-kit)](https://github.com/edgar0011/e1011-es-kit/blob/master/LICENSE)
+
+A tree-shakeable utility library for **Vanilla JS** and **React** projects. Provides hooks, UI components, state management, and general-purpose helpers through granular entry points — import only what you need.
+
+## Installation
 
 ```sh
-yarn install
+npm install @e1011/es-kit
+# or
+yarn add @e1011/es-kit
 ```
 
-## Run tests
+## Entry Points
 
-```sh
-yarn run test
+The library is fully tree-shakeable with `"sideEffects": false` and exposes multiple entry points so you can import exactly what you need:
+
+| Import path | Description | React required |
+|---|---|---|
+| `@e1011/es-kit` | Everything (hooks + utils + ui + constants) | Yes |
+| `@e1011/es-kit/hooks` | React hooks | Yes |
+| `@e1011/es-kit/utils` | Utility functions, state management, helpers | Partial (store hooks) |
+| `@e1011/es-kit/utils/ui` | UI helpers only (theme, classNames, noop, etc.) | No |
+| `@e1011/es-kit/ui` | React UI components + style utilities | Yes |
+
+### Vanilla JS usage
+
+For projects without React, use the framework-agnostic entry points:
+
+```js
+import { observeThemePreference, setThemeClassNames } from '@e1011/es-kit/utils/ui'
+import { createStore } from '@e1011/es-kit/utils'
+import { debounce, memoize } from '@e1011/es-kit/utils'
 ```
 
-## Author
+## Exports
+
+### Hooks (`@e1011/es-kit/hooks`)
+
+| Export | Description |
+|---|---|
+| `useApi` | Manages async API calls with loading/error/data states |
+| `useToggle`, `useToggle2` | Boolean state with toggle/setTrue/setFalse controls |
+| `useOutsideClick` | Detects clicks outside a referenced element |
+| `useResize` | Observes element resize with debouncing |
+| `useClassNames` | Memoized CSS class name composition |
+| `useParseProps` | Separates `data-*` attributes from other props |
+| `useThemePreference` | Observes system dark/light preference and applies theme |
+| `useAnimation` | GSAP-powered animated number transitions |
+| `useIntersectionObserver` | Observes element visibility in the viewport |
+| `useTimeoutFn` | Managed `setTimeout` with ready/clear/set controls |
+
+### Utils (`@e1011/es-kit/utils`)
+
+#### UI Helpers (`@e1011/es-kit/utils/ui`)
+
+| Export | Description |
+|---|---|
+| `classNames` | Combine CSS class names, filtering falsy values |
+| `parseProps` | Split props into `data-*` and rest categories |
+| `generateId` | Token-based unique ID generator |
+| `anchorClick` | Programmatic anchor navigation |
+| `noop` | Event handler that prevents default and stops propagation |
+| `mapSerReplacer` | JSON replacer for `Map` serialization |
+| `getBaseThemes` | Read theme config from an element |
+| `setThemeClassNames` | Set dark/light theme class names on an element |
+| `switchColorTheme` | Switch between dark and light theme classes |
+| `updateColorTheme` | Update theme based on current document state |
+| `observeThemePreference` | Observe `prefers-color-scheme` and apply theme automatically |
+
+#### Text & Value Operations
+
+| Export | Description |
+|---|---|
+| `toLowerCase`, `toUpperCase` | Case conversion |
+| `removeWhitespaces` | Strip all whitespace |
+| `normalizeString` | Normalize unicode accents |
+| `findStringInText` | Case/accent-insensitive search |
+| `escapeRegExp` | Escape regex special characters |
+| `truncateText` | Truncate text with indicator |
+| `sanitizeId`, `sanitizePathId` | Sanitize strings for use as IDs or URL paths |
+| `restrictNumberInLimits` | Clamp number between min/max |
+| `numberOperation` | Arithmetic with optional limits |
+| `incerementValue`, `decrementValue`, `setValue` | Number mutation with bounds |
+
+#### Object & Array Operations
+
+| Export | Description |
+|---|---|
+| `duplicatesInArray` | Find duplicate values |
+| `formatJsonString` | Pretty-print JSON (with GraphQL option) |
+| `formatObj`, `formatObj2` | Object-to-string formatting |
+| `chunkArray` | Split array into chunks |
+| `arrayToObjectTree` | Convert flat array to nested object tree |
+
+#### Async & Timing
+
+| Export | Description |
+|---|---|
+| `debounce` | Debounce function calls |
+| `delay` | Promise-based delay |
+| `memoize`, `memoizeComplex`, `memoizer` | Function memoization strategies |
+| `cancelableSetInterval`, `cancelableSetTimeout` | Cancelable timers |
 
-👤 **Martin Weiser**
+#### File & Validation
 
-* Website: https://www.linkedin.com/in/martinweiser
-* Github: [@edgar0011](https://github.com/edgar0011)
+| Export | Description |
+|---|---|
+| `validateCSVFile`, `validateSDFFile`, `validateJSONFile` | File format validation |
+| `parseCSVdata` | CSV string parsing |
+| `cleanCsvLines` | Remove empty lines from CSV |
+| `formatFilePath` | Extract filename from path |
+| `isBirthNumberValid` | CZ/SK birth number validation |
+| `emailMatcher` | Email domain matching |
 
-## Show your support
+#### Date & Time
 
-Give a ⭐️ if this project helped you!
+| Export | Description |
+|---|---|
+| `getTimeFromNow`, `getTimeTo` | Relative time formatting |
+| `getDateTime` | Date formatting with options |
+| `dateRangeFormat` | Date range formatting |
+
+#### Web Components
+
+| Export | Description |
+|---|---|
+| `customElementDefine` / `ced` | Custom element define decorator |
+| `createResolveAttribute`, `resolveAttributes` | Attribute resolvers for custom elements |
+
+#### State Management
+
+| Export | Description |
+|---|---|
+| `createStore` | Create a vanilla JS reactive store |
+| `createDataStore` | Store with built-in data loading state |
+| `useStore`, `useStoreApi` | React hooks for subscribing to stores |
+| `PeregrineMQ` | Pub/sub message queue |
+| `usePeregrineMQ` | React hook for PeregrineMQ |
+| `TinyStateMachine` | Lightweight state machine |
+
+#### Key Extraction
+
+| Export | Description |
+|---|---|
+| `keyExtractor` | Memoized key extraction from objects (key, id, or index) |
+
+### UI Components (`@e1011/es-kit/ui`)
+
+#### Atoms
+`Button`, `Text`, `Headline`, `Paragraph`, `Link`, `AnchorLink`, `Tag`, `Toggle`, `TextAndContent`, `Icon`, `IconBase`, `IconWC`
+
+#### Molecules
+`FlowLayout`, `PopoverLite`, `Tooltip`, `Popup`
+
+#### Containers
+`LayoutBox`, `LazyComponent`, `CollapsibleContainer`, `ResizableContainer`
+
+#### Other
+`Field`, `DividerLine`, `ErrorBoundary`
+
+#### Style Utilities
+`pxToRem`, `resolveStyleValue`, `toHex`, `convertHex`, `convertRGB`, `calculatePercColor`, `calculateColors`, `setDefaultFontSize`
+
+### Constants
+
+| Export | Description |
+|---|---|
+| `EventName` | Enum of DOM event names |
+| `KeyCode` | Enum of keyboard key codes |
+| `Alerts` | Enum of alert types (info, success, error, warning) |
+
+## Development
+
+```sh
+yarn install       # install dependencies
+yarn build         # full build (lint + typecheck + test + rollup + sass)
+yarn test          # run tests
+yarn lint          # lint source
+yarn storybook     # launch Storybook dev server
+```
+
+## Author
 
-## 📝 License
+**Martin Weiser**
+- GitHub: [@edgar0011](https://github.com/edgar0011)
+- LinkedIn: [martinweiser](https://www.linkedin.com/in/martinweiser)
 
-Copyright © 2023 [Martin Weiser](https://github.com/edgar0011).<br />
-This project is [MIT](https://github.com/edgar0011/e1011-es-kit/blob/master/LICENSE) licensed.
+## License
 
-***
-_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_
+[MIT](https://github.com/edgar0011/e1011-es-kit/blob/master/LICENSE)

package/dist/hooks/_virtual/_rollupPluginBabelHelpers.js

@@ -1,2 +1,2 @@
-"use strict";function e(e,r,t,n,o,i,c){try{var u=e[i](c),f=u.value}catch(e){return void t(e)}u.done?r(f):Promise.resolve(f).then(n,o)}function r(e,r,t){return(r=o(r))in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function t(e,r){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);r&&(n=n.filter((function(r){return Object.getOwnPropertyDescriptor(e,r).enumerable}))),t.push.apply(t,n)}return t}function n(e,r){if("object"!=typeof e||!e)return e;var t=e[Symbol.toPrimitive];if(void 0!==t){var n=t.call(e,r||"default");if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===r?String:Number)(e)}function o(e){var r=n(e,"string");return"symbol"==typeof r?r:r+""}exports.asyncToGenerator=function(r){return function(){var t=this,n=arguments;return new Promise((function(o,i){var c=r.apply(t,n);function u(r){e(c,o,i,u,f,"next",r)}function f(r){e(c,o,i,u,f,"throw",r)}u(void 0)}))}},exports.defineProperty=r,exports.objectSpread2=function(e){for(var n=1;n<arguments.length;n++){var o=null!=arguments[n]?arguments[n]:{};n%2?t(Object(o),!0).forEach((function(t){r(e,t,o[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(o)):t(Object(o)).forEach((function(r){Object.defineProperty(e,r,Object.getOwnPropertyDescriptor(o,r))}))}return e},exports.toPrimitive=n,exports.toPropertyKey=o;
+"use strict";function n(n,t,r,e,o,i,u){try{var c=n[i](u),a=c.value}catch(n){return void r(n)}c.done?t(a):Promise.resolve(a).then(e,o)}exports.asyncToGenerator=function(t){return function(){var r=this,e=arguments;return new Promise((function(o,i){var u=t.apply(r,e);function c(t){n(u,o,i,c,a,"next",t)}function a(t){n(u,o,i,c,a,"throw",t)}c(void 0)}))}};
 //# sourceMappingURL=_rollupPluginBabelHelpers.js.map

package/dist/hooks/esm/_virtual/_rollupPluginBabelHelpers.js

@@ -1,2 +1,2 @@
-function e(e,r,t,n,o,i,c){try{var u=e[i](c),a=u.value}catch(e){return void t(e)}u.done?r(a):Promise.resolve(a).then(n,o)}function r(r){return function(){var t=this,n=arguments;return new Promise((function(o,i){var c=r.apply(t,n);function u(r){e(c,o,i,u,a,"next",r)}function a(r){e(c,o,i,u,a,"throw",r)}u(void 0)}))}}function t(e,r,t){return(r=c(r))in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function n(e,r){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);r&&(n=n.filter((function(r){return Object.getOwnPropertyDescriptor(e,r).enumerable}))),t.push.apply(t,n)}return t}function o(e){for(var r=1;r<arguments.length;r++){var o=null!=arguments[r]?arguments[r]:{};r%2?n(Object(o),!0).forEach((function(r){t(e,r,o[r])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(o)):n(Object(o)).forEach((function(r){Object.defineProperty(e,r,Object.getOwnPropertyDescriptor(o,r))}))}return e}function i(e,r){if("object"!=typeof e||!e)return e;var t=e[Symbol.toPrimitive];if(void 0!==t){var n=t.call(e,r||"default");if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===r?String:Number)(e)}function c(e){var r=i(e,"string");return"symbol"==typeof r?r:r+""}export{r as asyncToGenerator,t as defineProperty,o as objectSpread2,i as toPrimitive,c as toPropertyKey};
+function n(n,r,t,o,e,i,u){try{var a=n[i](u),c=a.value}catch(n){return void t(n)}a.done?r(c):Promise.resolve(c).then(o,e)}function r(r){return function(){var t=this,o=arguments;return new Promise((function(e,i){var u=r.apply(t,o);function a(r){n(u,e,i,a,c,"next",r)}function c(r){n(u,e,i,a,c,"throw",r)}a(void 0)}))}}export{r as asyncToGenerator};
 //# sourceMappingURL=_rollupPluginBabelHelpers.js.map