@arkyn/components 3.0.1-beta.142 → 3.0.1-beta.144

package/dist/providers/modalProvider.js

@@ -2,90 +2,29 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useState } from "react";
 const modalContext = createContext({});
 /**
- * ModalProvider component - provides modal context for managing multiple modals state and data
+ * ModalProvider — context provider that manages open/close state and data for named modals.
  *
- * @param props - ModalProvider component properties
- * @param props.children - React elements that will have access to the modal context
- * @param props.enableModalAutomation - Optional flag to enable modal automation features
+ * Wrap your app (or a subtree) with this once. Any component in the tree can then call
+ * `useModal(key)` to open, close, or read data for a specific modal. `closeAll()` is also
+ * available (used by `useAutomation` to close all modals after a successful form action).
  *
- * @returns ModalProvider JSX element that wraps children with modal context
+ * @param props.children - Components that will have access to modal context.
+ *
+ * @returns ModalProvider JSX element.
  *
  * @example
  * ```tsx
- * // Basic modal provider setup
- * function App() {
- *   return (
- *     <ModalProvider>
- *       <UserModal />
- *       <ConfirmModal />
- *       <ImagePreviewModal />
- *       <MainContent />
- *     </ModalProvider>
- *   );
- * }
- *
- * // Modal provider with automation enabled
- * function AppWithAutomation() {
- *   return (
- *     <ModalProvider enableModalAutomation={true}>
- *       <Dashboard />
- *       <SettingsModal />
- *       <NotificationModal />
- *     </ModalProvider>
- *   );
- * }
- *
- * // Using with multiple modals
- * function MultiModalApp() {
- *   return (
- *     <ModalProvider>
- *       <Header />
- *       <Modal key="user-profile" />
- *       <Modal key="edit-settings" />
- *       <Modal key="confirm-delete" />
- *       <MainContent />
- *     </ModalProvider>
- *   );
- * }
- *
- * // Component using modal context
- * function ModalTrigger() {
- *   const { openModal, closeAll } = useModal();
- *
- *   const handleOpenUserModal = () => {
- *     openModal('user-details', { userId: 123, mode: 'edit' });
- *   };
- *
- *   const handleCloseAllModals = () => {
- *     closeAll();
- *   };
- *
- *   return (
- *     <div>
- *       <button onClick={handleOpenUserModal}>
- *         Open User Modal
- *       </button>
- *       <button onClick={handleCloseAllModals}>
- *         Close All Modals
- *       </button>
- *     </div>
- *   );
- * }
- *
- * // Modal component consuming context
- * function UserDetailsModal() {
- *   const { modalIsOpen, modalData, closeModal } = useModal('user-details');
+ * // In your root layout
+ * <ModalProvider>
+ *   <App />
+ * </ModalProvider>
  *
- *   if (!modalIsOpen) return null;
+ * // Opening a modal from anywhere in the tree
+ * const { openModal } = useModal();
+ * openModal('confirm-delete', { id: user.id });
  *
- *   return (
- *     <Modal onClose={() => closeModal('user-details')}>
- *       <h2>User Details</h2>
- *       <p>User ID: {modalData?.userId}</p>
- *       <p>Mode: {modalData?.mode}</p>
- *     </Modal>
- *   );
- * }
+ * // Consuming in the modal component
+ * const { modalIsOpen, modalData, closeModal } = useModal<{ id: number }>('confirm-delete');
  * ```
  */
 function ModalProvider(args) {

package/dist/providers/placesProvider.d.ts

@@ -5,22 +5,27 @@ type PlacesProviderProps = {
     preventFontsLoading?: boolean;
 };
 /**
- * PlacesProvider component that loads Google Maps API with Places, Marker, and Maps libraries.
+ * PlacesProvider — loads the Google Maps JS API with `places`, `marker`, and `maps` libraries.
+ *
+ * Uses a render-prop pattern: `children` receives `isLoaded` so you can defer rendering
+ * `SearchPlaces` or `MapView` until the script is ready.
+ *
+ * @param props.apiKey - Google Maps API key. Required.
+ * @param props.children - Render function: `(isLoaded: boolean) => ReactNode`.
+ * @param props.preventFontsLoading - Prevents Google Fonts from being injected by the Maps SDK. @default true
+ *
+ * @returns The result of calling `children(isLoaded)`.
  *
- * @component
  * @example
  * ```tsx
- * <PlacesProvider apiKey="YOUR_API_KEY">
- *   {(isLoaded) => isLoaded ? <MapComponent /> : <LoadingSpinner />)}
+ * <PlacesProvider apiKey={env.GOOGLE_MAPS_KEY}>
+ *   {(isLoaded) => (
+ *     isLoaded
+ *       ? <SearchPlaces apiKey={env.GOOGLE_MAPS_KEY} onSelect={setAddress} />
+ *       : <Skeleton />
+ *   )}
  * </PlacesProvider>
  * ```
- *
- * @param {PlacesProviderProps} props - The component props
- * @param {string} props.apiKey - Maps API key for authentication
- * @param {(isLoaded: boolean) => ReactNode} props.children - Render function that receives the loading state
- * @param {boolean} [props.preventFontsLoading=true] - Whether to prevent Fonts from loading
- *
- * @returns {ReactNode} The rendered children with the loading state
  */
 declare function PlacesProvider(props: PlacesProviderProps): import("react/jsx-runtime").JSX.Element;
 export { PlacesProvider };

package/dist/providers/placesProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"placesProvider.d.ts","sourceRoot":"","sources":["../../src/providers/placesProvider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAQlC,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,SAAS,CAAC;IAC3C,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AAEH,iBAAS,cAAc,CAAC,KAAK,EAAE,mBAAmB,2CAUjD;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"placesProvider.d.ts","sourceRoot":"","sources":["../../src/providers/placesProvider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAQlC,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,SAAS,CAAC;IAC3C,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iBAAS,cAAc,CAAC,KAAK,EAAE,mBAAmB,2CAUjD;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/providers/placesProvider.js

@@ -6,22 +6,27 @@ const libraries = [
     "maps",
 ];
 /**
- * PlacesProvider component that loads Google Maps API with Places, Marker, and Maps libraries.
+ * PlacesProvider — loads the Google Maps JS API with `places`, `marker`, and `maps` libraries.
+ *
+ * Uses a render-prop pattern: `children` receives `isLoaded` so you can defer rendering
+ * `SearchPlaces` or `MapView` until the script is ready.
+ *
+ * @param props.apiKey - Google Maps API key. Required.
+ * @param props.children - Render function: `(isLoaded: boolean) => ReactNode`.
+ * @param props.preventFontsLoading - Prevents Google Fonts from being injected by the Maps SDK. @default true
+ *
+ * @returns The result of calling `children(isLoaded)`.
  *
- * @component
  * @example
  * ```tsx
- * <PlacesProvider apiKey="YOUR_API_KEY">
- *   {(isLoaded) => isLoaded ? <MapComponent /> : <LoadingSpinner />)}
+ * <PlacesProvider apiKey={env.GOOGLE_MAPS_KEY}>
+ *   {(isLoaded) => (
+ *     isLoaded
+ *       ? <SearchPlaces apiKey={env.GOOGLE_MAPS_KEY} onSelect={setAddress} />
+ *       : <Skeleton />
+ *   )}
  * </PlacesProvider>
  * ```
- *
- * @param {PlacesProviderProps} props - The component props
- * @param {string} props.apiKey - Maps API key for authentication
- * @param {(isLoaded: boolean) => ReactNode} props.children - Render function that receives the loading state
- * @param {boolean} [props.preventFontsLoading=true] - Whether to prevent Fonts from loading
- *
- * @returns {ReactNode} The rendered children with the loading state
  */
 function PlacesProvider(props) {
     const { apiKey, children, preventFontsLoading = true } = props;

package/dist/providers/toastProvider.d.ts

@@ -11,36 +11,25 @@ type ToastProviderProps = {
 };
 declare const toastContext: import("react").Context<ToastContextProps>;
 /**
- * ToastProvider component - provides toast context for managing toast notifications
+ * ToastProvider — mounts a `react-hot-toast` `<Toaster>` and exposes `showToast` via context.
  *
- * @param props - ToastProvider component properties
- * @param props.children - React elements that will have access to the toast context
+ * Wrap your app once. Then call `useToast()` anywhere in the tree to show notifications.
+ * Supports two types: `"success"` (green) and `"danger"` (red).
  *
- * @returns ToastProvider JSX element that wraps children with toast context
+ * @param props.children - App subtree that will have access to `useToast`.
+ *
+ * @returns ToastProvider JSX element.
  *
  * @example
- * Basic usage:
  * ```tsx
+ * // In your root layout
  * <ToastProvider>
  *   <App />
  * </ToastProvider>
- * ```
- *
- * @example
- * Using toast in component:
- * ```tsx
- * function MyComponent() {
- *   const { showToast } = useToast();
- *
- *   const handleClick = () => {
- *     showToast({
- *       message: 'Success!',
- *       type: 'success'
- *     });
- *   };
  *
- *   return <button onClick={handleClick}>Show Toast</button>;
- * }
+ * // Anywhere in the tree
+ * const { showToast } = useToast();
+ * showToast({ message: "Order placed!", type: "success" });
  * ```
  */
 declare function ToastProvider({ children }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/providers/toastProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toastProvider.d.ts","sourceRoot":"","sources":["../../src/providers/toastProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAC;AAGjD,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC5B,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACpC,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF,QAAA,MAAM,YAAY,4CAAyC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iBAAS,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,kBAAkB,2CA2CtD;AAED,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"toastProvider.d.ts","sourceRoot":"","sources":["../../src/providers/toastProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAC;AAGjD,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC5B,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACpC,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF,QAAA,MAAM,YAAY,4CAAyC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,iBAAS,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,kBAAkB,2CA2CtD;AAED,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/providers/toastProvider.js

@@ -3,36 +3,25 @@ import { createContext } from "react";
 import toast, { Toaster } from "react-hot-toast";
 const toastContext = createContext({});
 /**
- * ToastProvider component - provides toast context for managing toast notifications
+ * ToastProvider — mounts a `react-hot-toast` `<Toaster>` and exposes `showToast` via context.
  *
- * @param props - ToastProvider component properties
- * @param props.children - React elements that will have access to the toast context
+ * Wrap your app once. Then call `useToast()` anywhere in the tree to show notifications.
+ * Supports two types: `"success"` (green) and `"danger"` (red).
  *
- * @returns ToastProvider JSX element that wraps children with toast context
+ * @param props.children - App subtree that will have access to `useToast`.
+ *
+ * @returns ToastProvider JSX element.
  *
  * @example
- * Basic usage:
  * ```tsx
+ * // In your root layout
  * <ToastProvider>
  *   <App />
  * </ToastProvider>
- * ```
- *
- * @example
- * Using toast in component:
- * ```tsx
- * function MyComponent() {
- *   const { showToast } = useToast();
- *
- *   const handleClick = () => {
- *     showToast({
- *       message: 'Success!',
- *       type: 'success'
- *     });
- *   };
  *
- *   return <button onClick={handleClick}>Show Toast</button>;
- * }
+ * // Anywhere in the tree
+ * const { showToast } = useToast();
+ * showToast({ message: "Order placed!", type: "success" });
  * ```
  */
 function ToastProvider({ children }) {

package/dist/services/toHtml.d.ts

@@ -1,18 +1,19 @@
 import { RichTextValue } from "../types/richTextTypes";
 /**
- * Converts a RichTextValue array to HTML string format.
+ * toHtml — converts a `RichTextValue` (Slate.js Descendant array) to an HTML string.
  *
- * @param {RichTextValue} richTextValue - Array of Descendant objects representing rich text content
- * @returns {string} HTML string representation of the rich text content
+ * Use this to persist or display the editor's content as plain HTML.
+ *
+ * @param richTextValue - The value from a `RichText` component's `onChange` callback.
+ * @returns HTML string representation of the rich text content.
  *
  * @example
- * ```typescript
- * const richTextService = new RichTextService();
- * const richText = [
- *   { type: 'paragraph', children: [{ text: 'Hello world', bold: true }] }
- * ];
- * const html = richTextService.toHtml(richText);
- * // Returns: "<p><strong>Hello world</strong></p>"
+ * ```tsx
+ * const [content, setContent] = useState<RichTextValue>([]);
+ *
+ * // On form submit, convert to HTML for storage
+ * const html = toHtml(content);
+ * // e.g. "<p><strong>Hello world</strong></p>"
  * ```
  */
 declare function toHtml(richTextValue: RichTextValue): string;

package/dist/services/toHtml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toHtml.d.ts","sourceRoot":"","sources":["../../src/services/toHtml.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD;;;;;;;;;;;;;;;GAeG;AAEH,iBAAS,MAAM,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAEpD;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"toHtml.d.ts","sourceRoot":"","sources":["../../src/services/toHtml.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD;;;;;;;;;;;;;;;;GAgBG;AAEH,iBAAS,MAAM,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAEpD;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/services/toHtml.js

@@ -1,18 +1,19 @@
 import { serialize } from "../utils/richTextUtilities";
 /**
- * Converts a RichTextValue array to HTML string format.
+ * toHtml — converts a `RichTextValue` (Slate.js Descendant array) to an HTML string.
  *
- * @param {RichTextValue} richTextValue - Array of Descendant objects representing rich text content
- * @returns {string} HTML string representation of the rich text content
+ * Use this to persist or display the editor's content as plain HTML.
+ *
+ * @param richTextValue - The value from a `RichText` component's `onChange` callback.
+ * @returns HTML string representation of the rich text content.
  *
  * @example
- * ```typescript
- * const richTextService = new RichTextService();
- * const richText = [
- *   { type: 'paragraph', children: [{ text: 'Hello world', bold: true }] }
- * ];
- * const html = richTextService.toHtml(richText);
- * // Returns: "<p><strong>Hello world</strong></p>"
+ * ```tsx
+ * const [content, setContent] = useState<RichTextValue>([]);
+ *
+ * // On form submit, convert to HTML for storage
+ * const html = toHtml(content);
+ * // e.g. "<p><strong>Hello world</strong></p>"
  * ```
  */
 function toHtml(richTextValue) {

package/dist/services/toRichTextValue.d.ts

@@ -1,26 +1,20 @@
 import { RichTextValue } from "../types/richTextTypes";
 /**
- * Converts an HTML string to RichTextValue format.
- * Parses the HTML content and transforms it into an array of Descendant objects
- * that can be used by the rich text editor.
+ * toRichTextValue — converts an HTML string to a `RichTextValue` (Slate.js Descendant array).
  *
- * @param {string} html - HTML string to be converted to rich text format
- * @returns {RichTextValue} Array of Descendant objects representing the parsed content
+ * Use this to populate a `RichText` editor with content previously stored as HTML
+ * (e.g. loaded from a database).
  *
- * @example
- * ```typescript
- * const richTextService = new RichTextService();
- * const html = "<p><strong>Hello world</strong></p>";
- * const richText = richTextService.toRichTextValue(html);
- * // Returns: [{ type: 'paragraph', children: [{ text: 'Hello world', bold: true }] }]
- * ```
+ * @param html - HTML string to convert.
+ * @returns Slate.js Descendant array ready to pass to `RichText`'s `defaultValue` prop.
  *
  * @example
- * ```typescript
- * // Handling plain text
- * const plainText = "Simple text";
- * const richText = richTextService.toRichTextValue(plainText);
- * // Returns: [{ text: 'Simple text' }]
+ * ```tsx
+ * // Load stored HTML into the editor
+ * const defaultValue = toRichTextValue(product.description);
+ * // e.g. [{ type: 'paragraph', children: [{ text: 'Hello', bold: true }] }]
+ *
+ * <RichText name="description" defaultValue={defaultValue} />
  * ```
  */
 declare function toRichTextValue(html: string): RichTextValue;

package/dist/services/toRichTextValue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toRichTextValue.d.ts","sourceRoot":"","sources":["../../src/services/toRichTextValue.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,iBAAS,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAYpD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"toRichTextValue.d.ts","sourceRoot":"","sources":["../../src/services/toRichTextValue.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGrE;;;;;;;;;;;;;;;;;GAiBG;AAEH,iBAAS,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAYpD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/services/toRichTextValue.js

@@ -1,27 +1,21 @@
 import parse from "html-react-parser";
 import { deserialize } from "../utils/richTextUtilities";
 /**
- * Converts an HTML string to RichTextValue format.
- * Parses the HTML content and transforms it into an array of Descendant objects
- * that can be used by the rich text editor.
+ * toRichTextValue — converts an HTML string to a `RichTextValue` (Slate.js Descendant array).
  *
- * @param {string} html - HTML string to be converted to rich text format
- * @returns {RichTextValue} Array of Descendant objects representing the parsed content
+ * Use this to populate a `RichText` editor with content previously stored as HTML
+ * (e.g. loaded from a database).
  *
- * @example
- * ```typescript
- * const richTextService = new RichTextService();
- * const html = "<p><strong>Hello world</strong></p>";
- * const richText = richTextService.toRichTextValue(html);
- * // Returns: [{ type: 'paragraph', children: [{ text: 'Hello world', bold: true }] }]
- * ```
+ * @param html - HTML string to convert.
+ * @returns Slate.js Descendant array ready to pass to `RichText`'s `defaultValue` prop.
  *
  * @example
- * ```typescript
- * // Handling plain text
- * const plainText = "Simple text";
- * const richText = richTextService.toRichTextValue(plainText);
- * // Returns: [{ text: 'Simple text' }]
+ * ```tsx
+ * // Load stored HTML into the editor
+ * const defaultValue = toRichTextValue(product.description);
+ * // e.g. [{ type: 'paragraph', children: [{ text: 'Hello', bold: true }] }]
+ *
+ * <RichText name="description" defaultValue={defaultValue} />
  * ```
  */
 function toRichTextValue(html) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyn/components",
-  "version": "3.0.1-beta.142",
+  "version": "3.0.1-beta.144",
   "main": "./dist/bundle.js",
   "module": "./dist/bundle.js",
   "types": "./dist/index.d.ts",