hintorium-react 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# Hintorium
+
+![npm](https://img.shields.io/npm/dw/hintorium-core)
+![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
+
+> Advanced, accessible, and fully customizable tooltip library for modern web apps.  
+> Built with TypeScript and SCSS.
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install hintorium-core
+# or
+pnpm add hintorium-core
+# or
+yarn add hintorium-core
+```
+
+---
+
+## 🧩 Usage
+
+Import the core script and styles in your app:
+
+```ts
+import { initTooltips } from "hintorium-core";
+import "hintorium-core/dist/core.css";
+
+initTooltips({
+  theme: "dark",
+  animation: "fade",
+  delay: 150,
+});
+```
+
+Then, in your HTML:
+
+```html
+<button data-tooltip="Save changes">💾 Save</button>
+```
+
+Hintorium automatically finds elements with `data-tooltip` attributes and applies positioning, animations, and themes.
+
+---
+
+## 🎨 Themes & Animations
+
+Available out of the box:
+
+**Themes:** `light`, `dark`, `glass`, `neon`, `pastel`, `gradient`  
+**Animations:** `fade`, `slide`, `zoom`, `bounce`
+
+You can customize them with SCSS variables or extend them via plugin API.
+
+---
+
+## ⚙️ Configuration
+
+| Option        | Type                                  | Default   | Description                      |
+| ------------- | ------------------------------------- | --------- | -------------------------------- |
+| `theme`       | `string`                              | `"light"` | Tooltip theme                    |
+| `delay`       | `number`                              | `150`     | Delay before showing tooltip     |
+| `animation`   | `string`                              | `"fade"`  | Entry/exit animation             |
+| `position`    | `"top" / "bottom" / "left" / "right"` | `"top"`   | Tooltip position                 |
+| `interactive` | `boolean`                             | `false`   | Allow hover/focus inside tooltip |
+
+---
+
+## 🧠 Accessibility
+
+- Fully ARIA-compliant
+- Keyboard accessible (`Tab`, `Esc`)
+- Screen-reader support
+- High-contrast mode compatible
+
+---
+
+## 📘 Documentation
+
+👉 Full documentation, examples, and live demos available at  
+[https://hintorium.vercel.app](https://hintorium.vercel.app)
+
+---
+
+## 🧱 Project Structure
+
+This library is part of the **Hintorium Monorepo**:
+
+```
+.
+├── apps/
+│   └── docs/           # documentation and examples
+└── packages/
+    └── hintorium/      # the core tooltip library
+```
+
+---
+
+## 🧾 License
+
+MIT © [Kamil Engineer](https://github.com/kamil-engineer)  
+See [LICENSE](https://github.com/kamil-engineer/Hintorium/blob/main/LICENSE)

package/dist/components/Tooltip.d.ts

@@ -0,0 +1,15 @@
+import { TooltipComponentProps } from '../types';
+
+/**
+ * Declarative tooltip component
+ * Wraps a single child element and adds tooltip functionality
+ *
+ * @example
+ * ```tsx
+ * <Tooltip content="Click me!" position="top" theme="dark">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ * ```
+ */
+export declare function Tooltip({ content, children, className, disabled, ...options }: TooltipComponentProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Tooltip.d.ts.map

package/dist/components/Tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../../src/components/Tooltip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGtD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,OAAO,EACX,EAAE,qBAAqB,2CAoBvB"}

package/dist/components/TooltipProvider.d.ts

@@ -0,0 +1,36 @@
+import { ReactNode } from 'react';
+import { TooltipOptions } from '../types';
+
+export interface TooltipProviderProps {
+    /**
+     * Child components
+     */
+    children: ReactNode;
+    /**
+     * Global tooltip options applied to all tooltips
+     */
+    options?: TooltipOptions;
+    /**
+     * Whether to initialize the global TooltipManager
+     * This enables data-tooltip attributes throughout the app
+     * @default true
+     */
+    initManager?: boolean;
+}
+/**
+ * Provider component for global tooltip configuration
+ * Wraps your app to provide consistent tooltip styling and behavior
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <TooltipProvider options={{ theme: 'dark', animation: 'fade' }}>
+ *       <YourApp />
+ *     </TooltipProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function TooltipProvider({ children, options, initManager, }: TooltipProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=TooltipProvider.d.ts.map

package/dist/components/TooltipProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TooltipProvider.d.ts","sourceRoot":"","sources":["../../src/components/TooltipProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG/C,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,OAAY,EACZ,WAAkB,GACnB,EAAE,oBAAoB,2CAUtB"}

package/dist/components/Tour.d.ts

@@ -0,0 +1,42 @@
+import { ReactNode } from 'react';
+import { TourStep } from '../types';
+import { useTour } from '../hooks/useTour';
+
+export interface TourProps {
+    /**
+     * Array of tour steps
+     */
+    steps: TourStep[];
+    /**
+     * Render prop function that receives tour controls
+     */
+    children: (tour: ReturnType<typeof useTour>) => ReactNode;
+}
+/**
+ * Render prop component for product tours
+ * Provides tour controls to children via render prop pattern
+ *
+ * @example
+ * ```tsx
+ * <Tour steps={[
+ *   { element: '#step1', content: 'First step' },
+ *   { element: '#step2', content: 'Second step' },
+ * ]}>
+ *   {(tour) => (
+ *     <div>
+ *       <button onClick={tour.start}>Start Tour</button>
+ *       {tour.isActive && (
+ *         <div>
+ *           <button onClick={tour.prev}>Previous</button>
+ *           <button onClick={tour.next}>Next</button>
+ *           <button onClick={tour.stop}>Exit</button>
+ *           <span>Step {tour.currentStep + 1}</span>
+ *         </div>
+ *       )}
+ *     </div>
+ *   )}
+ * </Tour>
+ * ```
+ */
+export declare function Tour({ steps, children }: TourProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Tour.d.ts.map

package/dist/components/Tour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tour.d.ts","sourceRoot":"","sources":["../../src/components/Tour.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAS,2CAGlD"}

package/dist/context/TooltipContext.d.ts

@@ -0,0 +1,16 @@
+import { TooltipOptions } from '../types';
+
+interface TooltipContextValue {
+    /**
+     * Global tooltip options that will be merged with individual tooltip options
+     */
+    options: TooltipOptions;
+}
+export declare const TooltipContext: import('react').Context<TooltipContextValue | null>;
+/**
+ * Hook to access tooltip context
+ * Returns null if not inside TooltipProvider
+ */
+export declare function useTooltipContext(): TooltipContextValue | null;
+export {};
+//# sourceMappingURL=TooltipContext.d.ts.map

package/dist/context/TooltipContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TooltipContext.d.ts","sourceRoot":"","sources":["../../src/context/TooltipContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,UAAU,mBAAmB;IAC3B;;OAEG;IACH,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,eAAO,MAAM,cAAc,qDAAkD,CAAC;AAE9E;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,GAAG,IAAI,CAE9D"}

package/dist/hooks/useAnalytics.d.ts

@@ -0,0 +1,8 @@
+export declare function useAnalytics(): {
+    data: Record<string, number>;
+    getCount: (id: string) => number;
+    increment: (id: string) => void;
+    resetAll: () => void;
+    refresh: () => void;
+};
+//# sourceMappingURL=useAnalytics.d.ts.map

package/dist/hooks/useAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnalytics.ts"],"names":[],"mappings":"AAGA,wBAAgB,YAAY;;mBAmBQ,MAAM;oBAPjC,MAAM;;;EAuBd"}

package/dist/hooks/useHintoriumI18n.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hook for internationalization (i18n)
+ * Provides translation functions and language management
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { t, language, setLanguage } = useI18n();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t('hintorium.tour.next')}</h1>
+ *       <button onClick={() => setLanguage('pl')}>Polski</button>
+ *       <button onClick={() => setLanguage('en')}>English</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHintoriumI18n(): {
+    language: string;
+    setLanguage: (lang: string) => void;
+    t: (key: string, fallback?: string) => string;
+    supportedLanguages: string[];
+};
+//# sourceMappingURL=useHintoriumI18n.d.ts.map

package/dist/hooks/useHintoriumI18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHintoriumI18n.d.ts","sourceRoot":"","sources":["../../src/hooks/useHintoriumI18n.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB;;wBAQH,MAAM;aAKjB,MAAM,aAAa,MAAM;;EAU1C"}

package/dist/hooks/useInlineHint.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Hook for creating inline hints
+ * Inline hints are persistent tooltips that appear inline with content
+ *
+ * @param content - Hint content
+ * @returns Ref to attach to the target element
+ *
+ * @example
+ * ```tsx
+ * function HelpText() {
+ *   const hintRef = useInlineHint('This is helpful information');
+ *
+ *   return (
+ *     <span ref={hintRef}>
+ *       Hover for help
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
+export declare function useInlineHint(content: string): React.RefCallback<HTMLElement>;
+/**
+ * Hook for initializing all inline hints in the DOM
+ * This scans for elements with data-inline-hint attribute
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useInlineHintManager();
+ *
+ *   return (
+ *     <div>
+ *       <span data-inline-hint="Helper text">Need help?</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useInlineHintManager(): void;
+//# sourceMappingURL=useInlineHint.d.ts.map

package/dist/hooks/useInlineHint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInlineHint.d.ts","sourceRoot":"","sources":["../../src/hooks/useInlineHint.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CA8B7E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,SAanC"}

package/dist/hooks/useTooltip.d.ts

@@ -0,0 +1,43 @@
+import { Tooltip, TooltipContentSource } from 'hintorium-core';
+import { UseTooltipOptions } from '../types';
+
+/**
+ * Hook for creating a tooltip on any element
+ *
+ * @param content - Tooltip content (string or HTML)
+ * @param options - Tooltip configuration options
+ * @returns Ref to attach to the target element
+ *
+ * @example
+ * ```tsx
+ * function MyButton() {
+ *   const tooltipRef = useTooltip('Click me!', { position: 'top' });
+ *   return <button ref={tooltipRef}>Hover me</button>;
+ * }
+ * ```
+ */
+export declare function useTooltip(content: TooltipContentSource, options?: UseTooltipOptions): React.RefCallback<HTMLElement>;
+/**
+ * Alternative hook that returns tooltip instance for manual control
+ *
+ * @example
+ * ```tsx
+ * function MyButton() {
+ *   const { ref, tooltip } = useTooltipInstance('Hello');
+ *
+ *   return (
+ *     <button
+ *       ref={ref}
+ *       onClick={() => tooltip?.show()}
+ *     >
+ *       Click to show
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTooltipInstance(content: string, options?: UseTooltipOptions): {
+    ref: (element: HTMLElement | null) => void;
+    tooltip: Tooltip | null;
+};
+//# sourceMappingURL=useTooltip.d.ts.map

package/dist/hooks/useTooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTooltip.d.ts","sourceRoot":"","sources":["../../src/hooks/useTooltip.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAIlD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CA4ChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,iBAAiB;mBAef,WAAW,GAAG,IAAI;;EAiC/B"}

package/dist/hooks/useTooltipAnalytics.d.ts

@@ -0,0 +1,4 @@
+import { UseTooltipOptions } from '../types';
+
+export declare function useTooltipAnalytics(options?: UseTooltipOptions): (originalOnShow?: (id: string) => void) => (id: string) => void;
+//# sourceMappingURL=useTooltipAnalytics.d.ts.map

package/dist/hooks/useTooltipAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTooltipAnalytics.d.ts","sourceRoot":"","sources":["../../src/hooks/useTooltipAnalytics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,iBAAiB,qBAEzC,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,UACxB,MAAM,UAUvB"}

package/dist/hooks/useTooltipManager.d.ts

@@ -0,0 +1,23 @@
+import { TooltipOptions } from '../types';
+
+/**
+ * Hook for initializing the global TooltipManager
+ * This automatically initializes all tooltips with data-tooltip attributes in the DOM
+ *
+ * @param options - Global tooltip options
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useTooltipManager({ theme: 'dark', animation: 'fade' });
+ *
+ *   return (
+ *     <div>
+ *       <button data-tooltip="I'm a tooltip!">Hover me</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTooltipManager(options?: TooltipOptions): import('hintorium-core/dist/types/tooltip/manager').TooltipManager | null;
+//# sourceMappingURL=useTooltipManager.d.ts.map

package/dist/hooks/useTooltipManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTooltipManager.d.ts","sourceRoot":"","sources":["../../src/hooks/useTooltipManager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,cAAc,6EAwBzD"}

package/dist/hooks/useTour.d.ts

@@ -0,0 +1,31 @@
+import { TourStep, UseTourReturn } from '../types';
+
+/**
+ * Hook for creating an interactive product tour
+ *
+ * @param steps - Array of tour steps
+ * @returns Tour control methods and state
+ *
+ * @example
+ * ```tsx
+ * function MyTour() {
+ *   const tour = useTour([
+ *     { element: '#step1', content: 'Welcome!' },
+ *     { element: '#step2', content: 'Click here to continue' },
+ *   ]);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={tour.start}>Start Tour</button>
+ *       {tour.isActive && (
+ *         <div>
+ *           Step {tour.currentStep + 1} of {steps.length}
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTour(steps: TourStep[]): UseTourReturn;
+//# sourceMappingURL=useTour.d.ts.map

package/dist/hooks/useTour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTour.d.ts","sourceRoot":"","sources":["../../src/hooks/useTour.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,aAAa,CA+GxD"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { Analytics, I18n } from 'hintorium-core';
+export { TooltipProvider } from './components/TooltipProvider';
+export type { TooltipProviderProps } from './components/TooltipProvider';
+export { Tooltip } from './components/Tooltip';
+export { Tour } from './components/Tour';
+export type { TourProps } from './components/Tour';
+export { useHintoriumI18n } from './hooks/useHintoriumI18n';
+export { useTooltipAnalytics } from './hooks/useTooltipAnalytics';
+export { useAnalytics } from './hooks/useAnalytics';
+export { useTooltip, useTooltipInstance } from './hooks/useTooltip';
+export { useTooltipManager } from './hooks/useTooltipManager';
+export { useTour } from './hooks/useTour';
+export { useInlineHint, useInlineHintManager } from './hooks/useInlineHint';
+export { useTooltipContext } from './context/TooltipContext';
+export type { TooltipOptions, TooltipPosition, TooltipTheme, TooltipAnimation, UseTooltipOptions, TooltipComponentProps, TourStep, UseTourReturn, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,YAAY,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC"}