@t007/utils 0.0.25 → 0.0.26

package/dist/scrollAssist-y9wFmYgt.d.ts

@@ -0,0 +1,72 @@
+type KeyEvent = Partial<KeyboardEvent> & Pick<KeyboardEvent, "key">;
+type Config = {
+    /** Enables or disables navigation logic. Defaults to `null`. */
+    enabled?: boolean | null;
+    /** CSS selector used to collect focusable nav items. Defaults to `"[data-arrow-item]"` */
+    selector?: string;
+    /** Whether hover should also move active selection. Defaults to `true`. */
+    focusOnHover?: boolean;
+    /** Whether directional movement wraps around edges. Defaults to `true`. */
+    loop?: boolean;
+    /** Enables virtual focus (aria-activedescendant) mode. Defaults to `false`. */
+    virtual?: boolean;
+    /** Enables alphanumeric type-ahead matching. Defaults to `false`. */
+    typeahead?: boolean;
+    /** Idle timeout before clearing type-ahead buffer (ms). Defaults to `500`. */
+    resetMs?: number;
+    /** Explicit RTL override; null auto-detects from computed style. Defaults to `null`. */
+    rtl?: boolean | null;
+    /** Enables roving tabindex when not in virtual mode. Defaults to `null`. */
+    rovingTab?: boolean | null;
+    /** Default tabbable index when no active item is selected. Defaults to `null`. */
+    defaultTabbableIndex?: number | null;
+    /** Base tabindex for non-active items, use `"-1"` to kill virtual list. Defaults to `"0"`. */
+    baseTabIndex?: string;
+    /** Class applied to active item in virtual mode. Defaults to `"focus-outlined"`. */
+    activeClass?: string;
+    /** Selector used for keyboard event source in virtual mode. Defaults to `"input[value],textarea,[contenteditable='true']"`. */
+    inputSelector?: string;
+    /** Scroll behavior options used when moving active item. Defaults to `{ block: "nearest", inline: "nearest" }`. */
+    scrollIntoView?: ScrollIntoViewOptions;
+    /** Focus behavior options used in non-virtual mode. Defaults to `{ preventScroll: false }`. */
+    focusOptions?: FocusOptions;
+    /** Explicit or computed grid dimensions for navigation math. Defaults to `{}`. */
+    grid?: Partial<Record<"x" | "y" | "vY", number>>;
+    /** Callback fired when an item becomes active/selected. */
+    onSelect?: (el: HTMLElement, e: KeyEvent) => void;
+    /** Callback fired when focus leaves the navigation container. */
+    onFocusOut?: (e: FocusEvent) => void;
+};
+
+type ScrollDir = "left" | "right" | "up" | "down";
+/** Scroll assist control object returned by initScrollAssist. */
+interface ScrollAssistHandle {
+    /** Recompute assist visibility. */
+    update: () => void;
+    /** Tear down observers and assist elements. */
+    destroy: () => void;
+}
+/** Configuration for scroll assist overlays. */
+interface ScrollAssistConfig {
+    /** Scroll speed in pixels per second. Defaults to `80`. */
+    pxPerSecond?: number;
+    /** Class name applied to assist overlays. Defaults to `"t007-scroll-assist"`. */
+    assistClassName?: string;
+    /** Enable vertical assist overlays. Defaults to `true`. */
+    vertical?: boolean;
+    /** Enable horizontal assist overlays. Defaults to `true`. */
+    horizontal?: boolean;
+}
+/** Hook to add edge-scrolling assist to an element. It creates invisible "hot zones" at the edges of the element that, when hovered or dragged into, will scroll the element in that direction.
+ * The assist is automatically disabled when the element is too small or contains interactive elements near the edges to prevent interference.
+ * @param el Scrollable element to enhance.
+ * @param options Scroll assist configuration.
+ * @returns Scroll assist controls or void when the element is already managed.
+ */
+declare function initScrollAssist(el: HTMLElement, { pxPerSecond, assistClassName, vertical, horizontal }?: ScrollAssistConfig): ScrollAssistHandle | void;
+/** Remove scroll assist from an element.
+ * @param el Target element.
+ */
+declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
+
+export { type Config as C, type KeyEvent as K, type ScrollAssistHandle as S, type ScrollAssistConfig as a, type ScrollDir as b, initScrollAssist as i, removeScrollAssist as r };

package/dist/styles/ripple.css

@@ -0,0 +1,55 @@
+:root {
+  --t007-ripple-initial-opacity: 0.4;
+  --t007-ripple-initial-scale: 0.5;
+  --t007-ripple-expand-scale: 2.05;
+  --t007-ripple-color: rgb(0 0 0 / 0.3);
+  --t007-ripple-expand-duration: 350ms;
+  --t007-ripple-fade-duration: 350ms;
+}
+
+:where(*:has(> .t007-ripple-wrapper)) {
+  position: relative;
+}
+
+.t007-ripple-wrapper {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  pointer-events: none;
+  border-radius: inherit;
+  contain: strict;
+}
+
+.t007-ripple {
+  position: absolute;
+  border-radius: 50%;
+  z-index: 0;
+  background-color: var(--t007-ripple-color);
+  transform: scale(0);
+}
+
+.t007-ripple-hold {
+  animation: t007-ripple-expand var(--t007-ripple-expand-duration) ease-out forwards;
+}
+
+.t007-ripple-fade {
+  animation: t007-ripple-fade var(--t007-ripple-fade-duration) ease-in forwards;
+}
+
+@keyframes t007-ripple-expand {
+  50% {
+    transform: scale(var(--t007-ripple-initial-scale));
+  }
+  to {
+    transform: scale(var(--t007-ripple-expand-scale));
+  }
+}
+
+@keyframes t007-ripple-fade {
+  from {
+    opacity: var(--t007-ripple-initial-opacity);
+  }
+  to {
+    opacity: 0;
+  }
+}

package/dist/styles/scroll-assist.css

@@ -0,0 +1,44 @@
+:root {
+  --t007-scroll-assist-color: rgb(0 0 0 / 1);
+  --t007-scroll-assist-opacity: 0.5;
+  --t007-scroll-assist-min-width: 2rem;
+  --t007-scroll-assist-height: 2rem;
+  --t007-scroll-assist-inline-offset: -0.35rem;
+  --t007-scroll-assist-block-offset: 0;
+}
+
+.t007-scroll-assist {
+  --t007-scroll-assist-gradient-dir: to right;
+  position: absolute;
+  min-width: var(--t007-scroll-assist-min-width);
+  height: 100%;
+  opacity: var(--t007-scroll-assist-opacity);
+  background: linear-gradient(var(--t007-scroll-assist-gradient-dir), transparent 0, var(--t007-scroll-assist-color) 30%, transparent);
+  z-index: 2;
+}
+
+.t007-scroll-assist[data-scroll-direction="left"] {
+  --t007-scroll-assist-gradient-dir: to right;
+  top: 0;
+  left: var(--t007-scroll-assist-inline-offset);
+}
+
+.t007-scroll-assist[data-scroll-direction="right"] {
+  --t007-scroll-assist-gradient-dir: to left;
+  top: 0;
+  right: var(--t007-scroll-assist-inline-offset);
+}
+
+.t007-scroll-assist[data-scroll-direction="up"] {
+  --t007-scroll-assist-gradient-dir: to bottom;
+  top: var(--t007-scroll-assist-block-offset);
+  height: var(--t007-scroll-assist-height);
+  width: 100%;
+}
+
+.t007-scroll-assist[data-scroll-direction="down"] {
+  --t007-scroll-assist-gradient-dir: to top;
+  bottom: var(--t007-scroll-assist-block-offset);
+  height: var(--t007-scroll-assist-height);
+  width: 100%;
+}

package/dist/useHighlight-DMpDCILK.d.cts

@@ -0,0 +1,19 @@
+interface HighlightOptions {
+    /** Whether to trim individual query strings. Defaults to `true`. */
+    trimQuery?: boolean;
+    /** Whether to match whole words only. Defaults to `false`. */
+    wholeWord?: boolean;
+}
+/** React hook to process a text string and identify parts that match a given query, returning an array of text chunks with information on whether they match the query.
+ * @param text The text to be processed.
+ * @param query The string or array of strings to match and highlight within the text.
+ * @param ignoreCase Whether the matching should be case-insensitive.
+ * @param options Additional options for the highlighting behavior.
+ * @returns An array of text chunks with highlight information.
+ */
+declare function useHighlight(text: string, query: string | string[], ignoreCase?: boolean, options?: HighlightOptions): {
+    text: string;
+    match: boolean;
+}[];
+
+export { type HighlightOptions as H, useHighlight as u };

package/dist/useHighlight-DMpDCILK.d.ts

@@ -0,0 +1,19 @@
+interface HighlightOptions {
+    /** Whether to trim individual query strings. Defaults to `true`. */
+    trimQuery?: boolean;
+    /** Whether to match whole words only. Defaults to `false`. */
+    wholeWord?: boolean;
+}
+/** React hook to process a text string and identify parts that match a given query, returning an array of text chunks with information on whether they match the query.
+ * @param text The text to be processed.
+ * @param query The string or array of strings to match and highlight within the text.
+ * @param ignoreCase Whether the matching should be case-insensitive.
+ * @param options Additional options for the highlighting behavior.
+ * @returns An array of text chunks with highlight information.
+ */
+declare function useHighlight(text: string, query: string | string[], ignoreCase?: boolean, options?: HighlightOptions): {
+    text: string;
+    match: boolean;
+}[];
+
+export { type HighlightOptions as H, useHighlight as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t007/utils",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "High-performance, zero-dependency utility functions for the t007 ecosystem.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",
@@ -15,20 +15,42 @@
   "module": "./dist/index.js",
   "browser": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "default": "./dist/index.js"
-    }
+    },
+    "./hooks/react": {
+      "types": "./dist/hooks/react.d.ts",
+      "import": "./dist/hooks/react.js",
+      "require": "./dist/hooks/react.cjs",
+      "default": "./dist/hooks/react.js"
+    },
+    "./hooks/vanilla": {
+      "types": "./dist/hooks/vanilla.d.ts",
+      "import": "./dist/hooks/vanilla.js",
+      "require": "./dist/hooks/vanilla.cjs",
+      "default": "./dist/hooks/vanilla.js"
+    },
+    "./components/react": {
+      "types": "./dist/components/react.d.ts",
+      "import": "./dist/components/react.js",
+      "require": "./dist/components/react.cjs",
+      "default": "./dist/components/react.js"
+    },
+    "./styles/ripple.css": "./dist/styles/ripple.css",
+    "./styles/scroll-assist.css": "./dist/styles/scroll-assist.css"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup --config tsup.config.ts && shx cp src/styles/ripple.css dist/styles/ripple.css && shx cp src/styles/scroll-assist.css dist/styles/scroll-assist.css",
     "prepublishOnly": "shx cp ../../LICENSE ."
   },
   "files": [
@@ -38,13 +60,29 @@
     "t007",
     "ecosystem",
     "vanilla-js",
+    "react",
     "utils",
     "helpers",
     "dom-manipulation",
     "shared-logic",
     "performance"
   ],
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
   "dependencies": {
+    "@t007/input": "^0.0.24",
     "sia-reactor": "^0.0.30"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }