@longline/aqua-ui 1.0.302 → 1.0.303

package/services/Toast/Toast.js

@@ -76,15 +76,46 @@ var CloseButton = styled.div(templateObject_2 || (templateObject_2 = __makeTempl
 var Action = styled.div(templateObject_3 || (templateObject_3 = __makeTemplateObject(["\n  display: flex;\n  align-items: center;\n  padding-left: 8px;\n  color: ", ";\n  cursor: pointer;\n  white-space: nowrap;\n  font: ", ";\n  text-transform: uppercase;\n  transition: color ease-in-out ", "ms;\n  &:hover {\n    color: ", ";\n  }\n  &:last-child {\n    padding-right: 16px;\n  }\n"], ["\n  display: flex;\n  align-items: center;\n  padding-left: 8px;\n  color: ", ";\n  cursor: pointer;\n  white-space: nowrap;\n  font: ", ";\n  text-transform: uppercase;\n  transition: color ease-in-out ", "ms;\n  &:hover {\n    color: ", ";\n  }\n  &:last-child {\n    padding-right: 16px;\n  }\n"])), function (p) { return p.theme.colors.primary[4]; }, function (p) { return p.theme.font.labelCaps; }, function (p) { return p.theme.animation.duration; }, function (p) { return p.theme.colors.primary[2]; });
 var ToastStyled = styled(ToastBase)(templateObject_4 || (templateObject_4 = __makeTemplateObject(["\n  // Position and size:\n  display: flex;\n  width: 344px;\n  box-sizing: border-box;\n  align-items: stretch;\n  justify-content: space-between;\n  user-select: none;\n  pointer-events: all;\n\n  // Space between toasts:\n  margin: 8px 0 8px 0; \n\n  // Appearance:\n  padding: 14px 0 14px 0;\n  background-color: ", ";\n  color: #fff;\n  border-radius: ", "px;\n  font: ", ";\n\n  // Content:\n  a {\n    color: ", " !important;\n  }\n\n  /* useTransitionState classes */\n  transition: opacity ", "ms ease;\n  &.preEnter, &.exiting, &.unmounted {\n    opacity: 0;\n  }\n  &.entering {\n    opacity: 1;\n  }\n  &.entered {\n    opacity: 1;\n  }\n\n"], ["\n  // Position and size:\n  display: flex;\n  width: 344px;\n  box-sizing: border-box;\n  align-items: stretch;\n  justify-content: space-between;\n  user-select: none;\n  pointer-events: all;\n\n  // Space between toasts:\n  margin: 8px 0 8px 0; \n\n  // Appearance:\n  padding: 14px 0 14px 0;\n  background-color: ", ";\n  color: #fff;\n  border-radius: ", "px;\n  font: ", ";\n\n  // Content:\n  a {\n    color: ", " !important;\n  }\n\n  /* useTransitionState classes */\n  transition: opacity ", "ms ease;\n  &.preEnter, &.exiting, &.unmounted {\n    opacity: 0;\n  }\n  &.entering {\n    opacity: 1;\n  }\n  &.entered {\n    opacity: 1;\n  }\n\n"])), function (p) { return p.theme.colors.primary[1]; }, function (p) { return p.theme.radius.normal; }, function (p) { return p.theme.font.bodyMedium; }, function (p) { return p.theme.colors.neutral[100]; }, function (p) { return p.theme.animation.duration * 2; });
 /**
- * A `Toast` is generated through the `ToastProvider.toast` method.
+ * A brief notification message that appears temporarily to provide feedback to the user.
  *
- * ```jsx
- * const toastProvider = useToast();
- * toastProvider.toast("Hello", {
+ * Toasts are typically created through the `useToast` hook rather than being rendered directly.
+ * They automatically disappear after a configurable duration, or can be manually dismissed
+ * by the user if `dismissable` is enabled.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * const { toast } = useToast();
+ *
+ * // Simple toast
+ * toast("Changes saved successfully");
+ *
+ * // Toast with options
+ * toast("File uploaded", {
  *   duration: 5000,
  *   dismissable: true
  * });
+ *
+ * // Toast with action button
+ * toast("Item deleted", {
+ *   action: () => undoDelete(),
+ *   actionLabel: "Undo"
+ * });
  * ```
+ *
+ * ## Toast Options
+ *
+ * | Option | Type | Default | Description |
+ * |--------|------|---------|-------------|
+ * | `duration` | `number` | `8000` | Auto-dismiss delay in ms. Set to `0` for persistent toast. |
+ * | `dismissable` | `boolean` | `false` | Show close button for manual dismissal |
+ * | `action` | `function` | - | Callback for action button click |
+ * | `actionLabel` | `ReactNode` | `"Action"` | Label for the action button |
+ *
+ * ## Animation
+ *
+ * Toasts fade in when appearing and fade out when dismissed or timed out.
+ * The animation duration is derived from the theme's animation settings.
  */
 var Toast = function (_a) {
     var _b = _a.duration, duration = _b === void 0 ? 8000 : _b, _c = _a.dismissable, dismissable = _c === void 0 ? false : _c, _d = _a.actionLabel, actionLabel = _d === void 0 ? "Action" : _d, props = __rest(_a, ["duration", "dismissable", "actionLabel"]);

package/services/Toast/ToastContainer.d.ts

@@ -30,11 +30,44 @@ interface IToastContainerProps {
     verticalOffset?: number;
 }
 /**
- * A `ToastContainer` displays any toasts generated through a `ToastProvider`,
- * which is a context that must wrap the ToastContainer.
+ * A container that renders and positions all active toasts from the `ToastProvider` context.
  *
- * By default, toasts appear in the bottom left corner of the screen, although
- * this can be adjusted through the alignment and offset properties.
+ * The `ToastContainer` must be placed inside a `ToastProvider`. It automatically subscribes
+ * to the toast context and renders any active toasts. The container itself is invisible and
+ * does not capture pointer events, but individual toasts within it do.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <ToastProvider>
+ *   <App />
+ *   <ToastContainer
+ *     verticalAlign="bottom"
+ *     horizontalAlign="right"
+ *   />
+ * </ToastProvider>
+ * ```
+ *
+ * ## Positioning
+ *
+ * Toasts can be positioned in any corner or centered horizontally:
+ *
+ * | Position | Props |
+ * |----------|-------|
+ * | Bottom-left | `verticalAlign="bottom" horizontalAlign="left"` (default) |
+ * | Bottom-right | `verticalAlign="bottom" horizontalAlign="right"` |
+ * | Bottom-center | `verticalAlign="bottom" horizontalAlign="center"` |
+ * | Top-left | `verticalAlign="top" horizontalAlign="left"` |
+ * | Top-right | `verticalAlign="top" horizontalAlign="right"` |
+ * | Top-center | `verticalAlign="top" horizontalAlign="center"` |
+ *
+ * Use `horizontalOffset` and `verticalOffset` to add padding from the edges.
+ *
+ * ## Stacking
+ *
+ * When multiple toasts are active, they stack vertically. With `verticalAlign="bottom"`,
+ * newer toasts appear above older ones. With `verticalAlign="top"`, newer toasts
+ * appear below older ones.
  */
 declare const ToastContainer: {
     ({ horizontalOffset, verticalOffset, verticalAlign, horizontalAlign, ...props }: IToastContainerProps): React.JSX.Element;

package/services/Toast/ToastContainer.js

@@ -40,19 +40,85 @@ var ToastContainerBase = function (props) {
 };
 var ToastContainerStyled = styled(ToastContainerBase)(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n  // Position:\n  // ToastContainer occupies all area that it can, but captures no pointer events.\n  // Toast children do capture pointer events.\n  position: absolute;\n  z-index: 9999;\n  top: ", "px;\n  bottom: ", "px;\n  left: ", "px;\n  right: ", "px;\n  pointer-events: none !important;\n  // Toasts are placed using a flexbox:\n  display: flex;\n  flex-direction: ", ";\n  align-items: ", ";\n  justify-content: ", ";\n"], ["\n  // Position:\n  // ToastContainer occupies all area that it can, but captures no pointer events.\n  // Toast children do capture pointer events.\n  position: absolute;\n  z-index: 9999;\n  top: ", "px;\n  bottom: ", "px;\n  left: ", "px;\n  right: ", "px;\n  pointer-events: none !important;\n  // Toasts are placed using a flexbox:\n  display: flex;\n  flex-direction: ", ";\n  align-items: ", ";\n  justify-content: ", ";\n"
     /**
-     * A `ToastContainer` displays any toasts generated through a `ToastProvider`,
-     * which is a context that must wrap the ToastContainer.
+     * A container that renders and positions all active toasts from the `ToastProvider` context.
      *
-     * By default, toasts appear in the bottom left corner of the screen, although
-     * this can be adjusted through the alignment and offset properties.
+     * The `ToastContainer` must be placed inside a `ToastProvider`. It automatically subscribes
+     * to the toast context and renders any active toasts. The container itself is invisible and
+     * does not capture pointer events, but individual toasts within it do.
+     *
+     * ## Usage
+     *
+     * ```tsx
+     * <ToastProvider>
+     *   <App />
+     *   <ToastContainer
+     *     verticalAlign="bottom"
+     *     horizontalAlign="right"
+     *   />
+     * </ToastProvider>
+     * ```
+     *
+     * ## Positioning
+     *
+     * Toasts can be positioned in any corner or centered horizontally:
+     *
+     * | Position | Props |
+     * |----------|-------|
+     * | Bottom-left | `verticalAlign="bottom" horizontalAlign="left"` (default) |
+     * | Bottom-right | `verticalAlign="bottom" horizontalAlign="right"` |
+     * | Bottom-center | `verticalAlign="bottom" horizontalAlign="center"` |
+     * | Top-left | `verticalAlign="top" horizontalAlign="left"` |
+     * | Top-right | `verticalAlign="top" horizontalAlign="right"` |
+     * | Top-center | `verticalAlign="top" horizontalAlign="center"` |
+     *
+     * Use `horizontalOffset` and `verticalOffset` to add padding from the edges.
+     *
+     * ## Stacking
+     *
+     * When multiple toasts are active, they stack vertically. With `verticalAlign="bottom"`,
+     * newer toasts appear above older ones. With `verticalAlign="top"`, newer toasts
+     * appear below older ones.
      */
-])), function (p) { return p.verticalAlign === 'top' ? p.verticalOffset : 0; }, function (p) { return p.verticalAlign === 'bottom' ? p.verticalOffset : 0; }, function (p) { return p.horizontalAlign === 'left' ? p.horizontalOffset : 0; }, function (p) { return p.horizontalAlign === 'right' ? p.horizontalOffset : 0; }, function (p) { return p.verticalAlign === 'top' ? 'column' : 'column-reverse'; }, function (p) { return p.horizontalAlign === 'left' ? 'start' : (p.horizontalAlign === 'right' ? 'end' : 'center'); }, function (p) { return p.verticalAlign == 'top' ? 'start' : 'end'; });
+])), function (p) { return p.verticalAlign === 'top' ? p.verticalOffset : 0; }, function (p) { return p.verticalAlign === 'bottom' ? p.verticalOffset : 0; }, function (p) { return p.horizontalAlign === 'left' ? p.horizontalOffset : 0; }, function (p) { return p.horizontalAlign === 'right' ? p.horizontalOffset : 0; }, function (p) { return p.verticalAlign === 'top' ? 'column' : 'column-reverse'; }, function (p) { return p.horizontalAlign === 'left' ? 'start' : (p.horizontalAlign === 'right' ? 'end' : 'center'); }, function (p) { return p.verticalAlign === 'top' ? 'start' : 'end'; });
 /**
- * A `ToastContainer` displays any toasts generated through a `ToastProvider`,
- * which is a context that must wrap the ToastContainer.
+ * A container that renders and positions all active toasts from the `ToastProvider` context.
+ *
+ * The `ToastContainer` must be placed inside a `ToastProvider`. It automatically subscribes
+ * to the toast context and renders any active toasts. The container itself is invisible and
+ * does not capture pointer events, but individual toasts within it do.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <ToastProvider>
+ *   <App />
+ *   <ToastContainer
+ *     verticalAlign="bottom"
+ *     horizontalAlign="right"
+ *   />
+ * </ToastProvider>
+ * ```
+ *
+ * ## Positioning
+ *
+ * Toasts can be positioned in any corner or centered horizontally:
+ *
+ * | Position | Props |
+ * |----------|-------|
+ * | Bottom-left | `verticalAlign="bottom" horizontalAlign="left"` (default) |
+ * | Bottom-right | `verticalAlign="bottom" horizontalAlign="right"` |
+ * | Bottom-center | `verticalAlign="bottom" horizontalAlign="center"` |
+ * | Top-left | `verticalAlign="top" horizontalAlign="left"` |
+ * | Top-right | `verticalAlign="top" horizontalAlign="right"` |
+ * | Top-center | `verticalAlign="top" horizontalAlign="center"` |
+ *
+ * Use `horizontalOffset` and `verticalOffset` to add padding from the edges.
+ *
+ * ## Stacking
  *
- * By default, toasts appear in the bottom left corner of the screen, although
- * this can be adjusted through the alignment and offset properties.
+ * When multiple toasts are active, they stack vertically. With `verticalAlign="bottom"`,
+ * newer toasts appear above older ones. With `verticalAlign="top"`, newer toasts
+ * appear below older ones.
  */
 var ToastContainer = function (_a) {
     var _b = _a.horizontalOffset, horizontalOffset = _b === void 0 ? 0 : _b, _c = _a.verticalOffset, verticalOffset = _c === void 0 ? 0 : _c, _d = _a.verticalAlign, verticalAlign = _d === void 0 ? 'bottom' : _d, _e = _a.horizontalAlign, horizontalAlign = _e === void 0 ? 'left' : _e, props = __rest(_a, ["horizontalOffset", "verticalOffset", "verticalAlign", "horizontalAlign"]);

package/services/Toast/ToastContext.d.ts

@@ -1,12 +1,12 @@
 import * as React from 'react';
-import { IToastMessage } from './IToastMessage';
-import { IToastProps } from './IToastProps';
+import type { IToastMessage } from './IToastMessage';
+import type { IToastProps } from './IToastProps';
 interface IToastContext {
     /**
      * Creates a new `Toast`, with the React node for content. Optional
      * properties can be provided.
      */
-    toast: (content: React.ReactNode, options: IToastProps) => void;
+    toast: (content: React.ReactNode, options?: IToastProps) => void;
     /**
      * Removes all toasts from the display.
      */
@@ -23,4 +23,5 @@ interface IToastContext {
     remove: (key: string) => void;
 }
 declare const ToastContext: React.Context<IToastContext>;
-export { ToastContext, IToastContext };
+export { ToastContext };
+export type { IToastContext };

package/services/Toast/ToastProvider.js

@@ -22,6 +22,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import * as React from 'react';
 import { ToastContext } from './ToastContext';
+var toastCounter = 0;
 /**
  * The `ToastProvider` is a React context that wraps both components that
  * generate toasts (through `useToast`) and the `ToastContainer` that displays
@@ -39,18 +40,22 @@ var ToastProvider = function (_a) {
      * can be provided.
      */
     var toast = function (content, options) {
-        setMessages(function (messages) {
+        setMessages(function (prevMessages) {
+            var _a;
+            var keys = Object.keys(prevMessages);
+            var newMessages = __assign({}, prevMessages);
             // Remove excess messages:
-            while (Object.keys(messages).length >= maxToasts) {
-                delete messages[Object.keys(messages)[0]];
+            while (keys.length >= maxToasts) {
+                var oldestKey = keys.shift();
+                var _b = newMessages, _c = oldestKey, _ = _b[_c], rest = __rest(_b, [typeof _c === "symbol" ? _c : _c + ""]);
+                newMessages = rest;
             }
-            // Create new message:
-            var key = new Date().getTime().toString();
-            messages[key] = {
+            // Create new message with unique key:
+            var key = "toast-".concat(++toastCounter);
+            return __assign(__assign({}, newMessages), (_a = {}, _a[key] = {
                 message: content,
                 options: options
-            };
-            return __assign({}, messages);
+            }, _a));
         });
     };
     /**
@@ -63,9 +68,9 @@ var ToastProvider = function (_a) {
      * Remove a toast from the display list by key.
      */
     var remove = function (key) {
-        setMessages(function (messages) {
-            delete messages[key];
-            return __assign({}, messages);
+        setMessages(function (prevMessages) {
+            var _a = prevMessages, _b = key, _ = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+            return rest;
         });
     };
     return (React.createElement(ToastContext.Provider, { value: { toast: toast, messages: messages, clear: clear, remove: remove } }, props.children));

package/services/Toast/useToast.d.ts

@@ -1,5 +1,41 @@
 /**
- * Returns the Toast Context.
+ * A hook that provides access to the toast notification system.
+ *
+ * Must be used within a `ToastProvider`. Returns an object with methods to create,
+ * remove, and manage toast notifications.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * const { toast, clear, remove, messages } = useToast();
+ *
+ * // Show a simple toast
+ * toast("Operation completed");
+ *
+ * // Show a toast with options
+ * toast("File saved", { duration: 3000, dismissable: true });
+ *
+ * // Show a toast with an action
+ * toast("Email sent", {
+ *   action: () => openEmail(),
+ *   actionLabel: "View"
+ * });
+ *
+ * // Clear all toasts
+ * clear();
+ * ```
+ *
+ * ## Returned Object
+ *
+ * | Property | Type | Description |
+ * |----------|------|-------------|
+ * | `toast` | `(content, options?) => void` | Create a new toast notification |
+ * | `clear` | `() => void` | Remove all active toasts |
+ * | `remove` | `(key) => void` | Remove a specific toast by key |
+ * | `messages` | `object` | Current active toasts (for advanced use) |
+ *
+ * @throws Error if called outside of a `ToastProvider`
+ * @returns The toast context with methods to manage notifications
  */
 declare const useToast: () => import("./ToastContext").IToastContext;
 export { useToast };

package/services/Toast/useToast.js

@@ -1,9 +1,49 @@
 import * as React from 'react';
 import { ToastContext } from './ToastContext';
 /**
- * Returns the Toast Context.
+ * A hook that provides access to the toast notification system.
+ *
+ * Must be used within a `ToastProvider`. Returns an object with methods to create,
+ * remove, and manage toast notifications.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * const { toast, clear, remove, messages } = useToast();
+ *
+ * // Show a simple toast
+ * toast("Operation completed");
+ *
+ * // Show a toast with options
+ * toast("File saved", { duration: 3000, dismissable: true });
+ *
+ * // Show a toast with an action
+ * toast("Email sent", {
+ *   action: () => openEmail(),
+ *   actionLabel: "View"
+ * });
+ *
+ * // Clear all toasts
+ * clear();
+ * ```
+ *
+ * ## Returned Object
+ *
+ * | Property | Type | Description |
+ * |----------|------|-------------|
+ * | `toast` | `(content, options?) => void` | Create a new toast notification |
+ * | `clear` | `() => void` | Remove all active toasts |
+ * | `remove` | `(key) => void` | Remove a specific toast by key |
+ * | `messages` | `object` | Current active toasts (for advanced use) |
+ *
+ * @throws Error if called outside of a `ToastProvider`
+ * @returns The toast context with methods to manage notifications
  */
 var useToast = function () {
-    return React.useContext(ToastContext);
+    var context = React.useContext(ToastContext);
+    if (context === null) {
+        throw new Error('useToast must be used within a ToastProvider');
+    }
+    return context;
 };
 export { useToast };