akanjs 3.0.0-alpha.104 → 3.0.0-alpha.105

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.104",
+  "version": "3.0.0-alpha.105",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/rscPagePrompts.ts

@@ -165,7 +165,8 @@ export class RscPagePrompts {
     const status = (error as { statusCode?: unknown } | null)?.statusCode;
     if (status === 401 || status === 403)
       return { ok: false, reason: "forbidden", message: `A query the screen makes refused the caller (${status}).` };
-    if (status === 404) return { ok: false, reason: "not-found", message: "A document the screen reads does not exist." };
+    if (status === 404)
+      return { ok: false, reason: "not-found", message: "A document the screen reads does not exist." };
     RscPagePrompts.logger.warn(
       `page prompt body threw: ${error instanceof Error ? (error.stack ?? error.message) : error}`,
     );

package/types/ui/Toast.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+export type ToastType = "info" | "success" | "error" | "warning" | "loading";
+export interface ToastMessage {
+    key: string;
+    type: ToastType;
+    content: ReactNode;
+    /** Seconds the message is shown before the shell starts its exit. */
+    duration: number;
+    /** The shell started this message's exit: play the leave animation, then call `onClosed`. */
+    leaving: boolean;
+}
+export interface ToastItemProps {
+    className?: string;
+    message: ToastMessage;
+    /** Dismisses early — starts the same exit the timer would. */
+    onClose: () => void;
+    /** Takes the message off the screen. Call it when the exit animation has finished. */
+    onClosed: () => void;
+}
+export declare const DefaultToastItem: ({ className, message, onClose, onClosed }: ToastItemProps) => import("react/jsx-runtime").JSX.Element;
+export interface ToastProps {
+    className?: string;
+    /** Oldest first, already capped by the store. A replacement showing fewer slices the list itself. */
+    messages: ToastMessage[];
+    /** The device's top safe area in pixels — the stack starts below it. */
+    topSafeArea: number;
+    /** Starts a message's exit, as the dismiss button and the elapsed timer both do. */
+    onClose: (key: string) => void;
+    /** Takes a message off the screen once its exit animation has finished. */
+    onClosed: (key: string) => void;
+}
+export declare const DefaultToast: ({ className, messages, topSafeArea, onClose, onClosed }: ToastProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * The toast surface. `Toast` (the stack) and `Toast.Item` (one card) each resolve to a route-scoped override
+ * when a `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `Toast`, `ToastItem`).
+ *
+ * `System`'s `Messages` renders this and is not a slot: it keeps the `msg.*` wiring, the store read, the
+ * body-level portal and the dismiss timers, so a replacement re-skins the surface without re-implementing
+ * when a toast appears and goes away.
+ */
+export declare const Toast: import("react").ComponentType<ToastProps> & {
+    Item: import("react").ComponentType<ToastItemProps>;
+};

package/types/ui/UiOverride/context.d.ts

@@ -29,6 +29,7 @@ import type { ItemProps as RadioItemProps, RadioProps } from "../Radio.d.ts";
 import type { BadgeVariants, ButtonVariants, InputSurfaceVariants } from "../recipe.d.ts";
 import type { SelectProps } from "../Select.d.ts";
 import type { TableProps } from "../Table.d.ts";
+import type { ToastItemProps, ToastProps } from "../Toast.d.ts";
 import type { MultiProps as ToggleSelectMultiProps, ToggleSelectProps } from "../ToggleSelect.d.ts";
 import type { TooltipProps } from "../Tooltip.d.ts";
 import type { UnauthorizedProps } from "../Unauthorized.d.ts";
@@ -79,6 +80,8 @@ export interface AkanUiOverrides {
     DatePicker: ComponentType<DatePickerProps>;
     DatePickerRangePicker: ComponentType<RangePickerProps>;
     DatePickerTimePicker: ComponentType<TimePickerProps>;
+    Toast: ComponentType<ToastProps>;
+    ToastItem: ComponentType<ToastItemProps>;
     ToggleSelect: ComponentType<ToggleSelectProps<string | number | boolean | null>>;
     ToggleSelectMulti: ComponentType<ToggleSelectMultiProps>;
     LoadingSpin: ComponentType<SpinProps>;

package/types/ui/index.d.ts

@@ -67,6 +67,7 @@ export { Switch, type SwitchProps } from "./Switch.d.ts";
 export { System, type WebAppManifest } from "./System.d.ts";
 export { Tab } from "./Tab.d.ts";
 export { Table } from "./Table.d.ts";
+export { DefaultToast, DefaultToastItem, Toast, type ToastItemProps, type ToastMessage, type ToastProps, type ToastType, } from "./Toast.d.ts";
 export { ToggleSelect } from "./ToggleSelect.d.ts";
 export { Tooltip, type TooltipProps } from "./Tooltip.d.ts";
 export { type AkanModalComponent, type AkanUiOverrideManifest, type AkanUiOverrideName, type AkanUiOverrides, type AkanUiRecipes, createOverridable, override, UiOverrideProvider, type UiOverrideProviderProps, useUiOverride, useUiRecipe, } from "./UiOverride.d.ts";

package/ui/System/Messages.tsx

@@ -1,132 +1,91 @@
 "use client";
-import { cn, msg, usePage } from "akanjs/client";
+import { msg, usePage } from "akanjs/client";
 import { st } from "akanjs/store";
-import { type ReactNode, useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import {
-  AiOutlineCheckCircle,
-  AiOutlineClose,
-  AiOutlineExclamationCircle,
-  AiOutlineInfoCircle,
-  AiOutlineLoading3Quarters,
-  AiOutlineWarning,
-} from "react-icons/ai";
 
-type MessageType = "success" | "error" | "info" | "warning" | "loading";
+import { Toast, type ToastMessage } from "../Toast";
 
-interface MessageProps {
-  content: ReactNode;
-  type?: MessageType;
-  duration: number; 
-  keyForMessage: string;
-}
-
-interface TimeOutType {
-  key: string;
-  timeoutId: NodeJS.Timeout;
-}
 interface MsgOption {
   key?: string;
   duration?: number;
   data?: Record<string, string | number>;
 }
 
-const messageTone: { [key in MessageType]: { card: string; chip: string; icon: ReactNode } } = {
-  info: { card: "border-info/35", chip: "bg-info/15 text-info", icon: <AiOutlineInfoCircle /> },
-  success: { card: "border-success/35", chip: "bg-success/15 text-success", icon: <AiOutlineCheckCircle /> },
-  warning: { card: "border-warning/35", chip: "bg-warning/15 text-warning", icon: <AiOutlineWarning /> },
-  error: {
-    card: "border-destructive/35",
-    chip: "bg-destructive/15 text-destructive",
-    icon: <AiOutlineExclamationCircle />,
-  },
-  loading: {
-    card: "border-border",
-    chip: "bg-muted text-foreground/60",
-    icon: <AiOutlineLoading3Quarters className="animate-spin" />,
-  },
-};
-
-let timeOuts: TimeOutType[] = [];
-
-const Message = ({ content, type = "info" as MessageType, duration, keyForMessage }: MessageProps) => {
-  const [preBlind, setPreBlind] = useState(false);
-  useEffect(() => {
-    if (!content) return;
-    
-    const existingTimeOut = timeOuts.find((item) => item.key === keyForMessage);
-    if (existingTimeOut) {
-      clearTimeout(existingTimeOut.timeoutId);
-      removeTimeOut(keyForMessage);
-    }
-
-    const timeoutId = setTimeout(() => {
-      setPreBlind(true);
-    }, duration * 1000);
-    addTimeOut(keyForMessage, timeoutId);
-
-    return () => {
-      clearTimeout(timeoutId);
-    };
-  }, [content, keyForMessage, type]);
-
-  useEffect(() => {
-    if (!preBlind) return;
-    setTimeout(() => {
-      st.do.hideMessage(keyForMessage);
-      removeTimeOut(keyForMessage);
-    }, 100);
-  }, [preBlind]);
-
-  const addTimeOut = (key: string, timeoutId: NodeJS.Timeout) => {
-    const filteredTimeOuts = timeOuts.filter((item) => item.key !== key);
-    timeOuts = [...filteredTimeOuts, { key, timeoutId }];
-  };
-
-  const removeTimeOut = (key: string) => {
-    timeOuts = timeOuts.filter((item) => item.key !== key);
-  };
+interface ArmedMessage {
+  message: Omit<ToastMessage, "leaving">;
+  timeoutId: ReturnType<typeof setTimeout>;
+}
 
-  const tone = messageTone[type];
-  return (
-    <div
-      data-state={preBlind}
-      className="pointer-events-auto w-full animate-fadeInDown15-150ms data-[state=true]:animate-smaller"
-    >
-      <div
-        className={cn(
-          "flex w-full items-start gap-3 rounded-box border bg-popover/95 p-3 text-popover-foreground shadow-lg backdrop-blur-sm",
-          tone.card,
-        )}
-      >
-        <div className={cn("flex size-7 shrink-0 items-center justify-center rounded-full text-base", tone.chip)}>
-          {tone.icon}
-        </div>
-        <span className="min-w-0 flex-1 self-center break-words text-sm leading-snug">{content}</span>
-        <button
-          aria-label="Dismiss"
-          className="-mr-1 shrink-0 self-center rounded-full p-1 text-foreground/30 transition-colors hover:text-foreground/70"
-          onClick={() => {
-            setPreBlind(true);
-          }}
-          type="button"
-        >
-          <AiOutlineClose className="text-sm" />
-        </button>
-      </div>
-    </div>
-  );
-};
+const exitGraceMs = 2000;
 
 export const Messages = () => {
   const messages = st.use.messages({ agent: false });
   const pageState = st.use.pageState({ agent: false });
   const { l } = usePage();
   const [portalElement, setPortalElement] = useState<HTMLElement | null>(null);
+  const [leavingKeys, setLeavingKeys] = useState<string[]>([]);
+  const timers = useRef(new Map<string, ArmedMessage>());
+
+  const dropMessage = (key: string) => {
+    const armed = timers.current.get(key);
+    if (armed) {
+      clearTimeout(armed.timeoutId);
+      timers.current.delete(key);
+    }
+    setLeavingKeys((keys) => keys.filter((leavingKey) => leavingKey !== key));
+    st.do.hideMessage(key);
+  };
+
+  const startLeaving = (key: string) => {
+    const armed = timers.current.get(key);
+    if (armed) {
+      clearTimeout(armed.timeoutId);
+      timers.current.set(key, { message: armed.message, timeoutId: setTimeout(() => dropMessage(key), exitGraceMs) });
+    }
+    setLeavingKeys((keys) => (keys.includes(key) ? keys : [...keys, key]));
+  };
+
   useEffect(() => {
     if (typeof document === "undefined") return;
     setPortalElement(document.body);
   }, []);
+
+  useEffect(() => {
+    const running = timers.current;
+    const rearmed: string[] = [];
+    for (const message of messages) {
+      const armed = running.get(message.key);
+
+      if (armed?.message === message) continue;
+      if (armed) {
+        clearTimeout(armed.timeoutId);
+        rearmed.push(message.key);
+      }
+      running.set(message.key, {
+        message,
+        timeoutId: setTimeout(() => startLeaving(message.key), message.duration * 1000),
+      });
+    }
+    for (const [key, armed] of [...running]) {
+      if (messages.some((message) => message.key === key)) continue;
+      clearTimeout(armed.timeoutId);
+      running.delete(key);
+    }
+    setLeavingKeys((keys) => {
+      const alive = keys.filter((key) => !rearmed.includes(key) && messages.some((message) => message.key === key));
+      return alive.length === keys.length ? keys : alive;
+    });
+  }, [messages]);
+
+  useEffect(() => {
+    const running = timers.current;
+    return () => {
+      for (const armed of running.values()) clearTimeout(armed.timeoutId);
+      running.clear();
+    };
+  }, []);
+
   useEffect(() => {
     Object.assign(msg, {
       info: (msgKey: `${string}.${string}`, option = {} as MsgOption) => {
@@ -172,23 +131,18 @@ export const Messages = () => {
     });
   }, []);
   if (!messages.length || !portalElement) return null;
+  const toastMessages: ToastMessage[] = messages.map((message) => ({
+    ...message,
+    leaving: leavingKeys.includes(message.key),
+  }));
 
   return createPortal(
-    <div
-      id="toast"
-      className="pointer-events-none fixed top-0 left-1/2 z-[100] flex h-fit w-full max-w-md -translate-x-1/2 flex-col items-center gap-2 px-4 pt-3"
-      style={{ marginTop: pageState.topSafeArea }}
-    >
-      {messages.map((message) => (
-        <Message
-          content={message.content}
-          type={message.type}
-          duration={message.duration}
-          key={message.key}
-          keyForMessage={message.key}
-        />
-      ))}
-    </div>,
+    <Toast
+      messages={toastMessages}
+      topSafeArea={pageState.topSafeArea}
+      onClose={startLeaving}
+      onClosed={dropMessage}
+    />,
     portalElement,
   );
 };

package/ui/Toast.tsx

@@ -0,0 +1,132 @@
+"use client";
+import { cn } from "akanjs/client";
+import type { ReactNode } from "react";
+import {
+  AiOutlineCheckCircle,
+  AiOutlineClose,
+  AiOutlineExclamationCircle,
+  AiOutlineInfoCircle,
+  AiOutlineLoading3Quarters,
+  AiOutlineWarning,
+} from "react-icons/ai";
+
+import { createOverridable } from "./UiOverride";
+
+export type ToastType = "info" | "success" | "error" | "warning" | "loading";
+
+export interface ToastMessage {
+  key: string;
+  type: ToastType;
+  content: ReactNode;
+  /** Seconds the message is shown before the shell starts its exit. */
+  duration: number;
+  /** The shell started this message's exit: play the leave animation, then call `onClosed`. */
+  leaving: boolean;
+}
+
+const messageTone: { [key in ToastType]: { card: string; chip: string; icon: ReactNode } } = {
+  info: { card: "border-info/35", chip: "bg-info/15 text-info", icon: <AiOutlineInfoCircle /> },
+  success: { card: "border-success/35", chip: "bg-success/15 text-success", icon: <AiOutlineCheckCircle /> },
+  warning: { card: "border-warning/35", chip: "bg-warning/15 text-warning", icon: <AiOutlineWarning /> },
+  error: {
+    card: "border-destructive/35",
+    chip: "bg-destructive/15 text-destructive",
+    icon: <AiOutlineExclamationCircle />,
+  },
+  loading: {
+    card: "border-border",
+    chip: "bg-muted text-foreground/60",
+    icon: <AiOutlineLoading3Quarters className="animate-spin" />,
+  },
+};
+
+export interface ToastItemProps {
+  className?: string;
+  message: ToastMessage;
+  /** Dismisses early — starts the same exit the timer would. */
+  onClose: () => void;
+  /** Takes the message off the screen. Call it when the exit animation has finished. */
+  onClosed: () => void;
+}
+
+export const DefaultToastItem = ({ className, message, onClose, onClosed }: ToastItemProps) => {
+  const tone = messageTone[message.type];
+  return (
+    <div
+      data-state={message.leaving ? "out" : "in"}
+      onAnimationEnd={() => {
+        if (message.leaving) onClosed();
+      }}
+      className={cn(
+        "pointer-events-auto w-full data-[state=in]:animate-fadeInDown15-150ms data-[state=out]:animate-smaller",
+        className,
+      )}
+    >
+      <div
+        className={cn(
+          "flex w-full items-start gap-3 rounded-box border bg-popover/95 p-3 text-popover-foreground shadow-lg backdrop-blur-sm",
+          tone.card,
+        )}
+      >
+        <div className={cn("flex size-7 shrink-0 items-center justify-center rounded-full text-base", tone.chip)}>
+          {tone.icon}
+        </div>
+        <span className="min-w-0 flex-1 self-center break-words text-sm leading-snug">{message.content}</span>
+        <button
+          aria-label="Dismiss"
+          className="-mr-1 shrink-0 self-center rounded-full p-1 text-foreground/30 transition-colors hover:text-foreground/70"
+          onClick={onClose}
+          type="button"
+        >
+          <AiOutlineClose className="text-sm" />
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export interface ToastProps {
+  className?: string;
+  /** Oldest first, already capped by the store. A replacement showing fewer slices the list itself. */
+  messages: ToastMessage[];
+  /** The device's top safe area in pixels — the stack starts below it. */
+  topSafeArea: number;
+  /** Starts a message's exit, as the dismiss button and the elapsed timer both do. */
+  onClose: (key: string) => void;
+  /** Takes a message off the screen once its exit animation has finished. */
+  onClosed: (key: string) => void;
+}
+
+export const DefaultToast = ({ className, messages, topSafeArea, onClose, onClosed }: ToastProps) => (
+  <div
+    id="toast"
+    className={cn(
+      "pointer-events-none fixed top-0 left-1/2 z-[100] flex h-fit w-full max-w-md -translate-x-1/2 flex-col items-center gap-2 px-4 pt-3",
+      className,
+    )}
+    style={{ marginTop: topSafeArea }}
+  >
+    {messages.map((message) => (
+      <Toast.Item
+        key={message.key}
+        message={message}
+        onClose={() => onClose(message.key)}
+        onClosed={() => onClosed(message.key)}
+      />
+    ))}
+  </div>
+);
+
+const ToastBase = createOverridable("Toast", DefaultToast);
+
+/**
+ * The toast surface. `Toast` (the stack) and `Toast.Item` (one card) each resolve to a route-scoped override
+ * when a `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `Toast`, `ToastItem`).
+ *
+ * `System`'s `Messages` renders this and is not a slot: it keeps the `msg.*` wiring, the store read, the
+ * body-level portal and the dismiss timers, so a replacement re-skins the surface without re-implementing
+ * when a toast appears and goes away.
+ */
+export const Toast = Object.assign(ToastBase, {
+  Item: createOverridable("ToastItem", DefaultToastItem),
+});

package/ui/UiOverride/context.ts

@@ -31,6 +31,7 @@ import type { ItemProps as RadioItemProps, RadioProps } from "../Radio";
 import type { BadgeVariants, ButtonVariants, InputSurfaceVariants } from "../recipe";
 import type { SelectProps } from "../Select";
 import type { TableProps } from "../Table";
+import type { ToastItemProps, ToastProps } from "../Toast";
 import type { MultiProps as ToggleSelectMultiProps, ToggleSelectProps } from "../ToggleSelect";
 import type { TooltipProps } from "../Tooltip";
 import type { UnauthorizedProps } from "../Unauthorized";
@@ -90,6 +91,9 @@ export interface AkanUiOverrides {
   DatePickerRangePicker: ComponentType<RangePickerProps>;
   DatePickerTimePicker: ComponentType<TimePickerProps>;
 
+  Toast: ComponentType<ToastProps>;
+  ToastItem: ComponentType<ToastItemProps>;
+
   ToggleSelect: ComponentType<ToggleSelectProps<string | number | boolean | null>>;
   ToggleSelectMulti: ComponentType<ToggleSelectMultiProps>;
 

package/ui/index.ts

@@ -108,6 +108,15 @@ export { Switch, type SwitchProps } from "./Switch";
 export { System, type WebAppManifest } from "./System";
 export { Tab } from "./Tab";
 export { Table } from "./Table";
+export {
+  DefaultToast,
+  DefaultToastItem,
+  Toast,
+  type ToastItemProps,
+  type ToastMessage,
+  type ToastProps,
+  type ToastType,
+} from "./Toast";
 export { ToggleSelect } from "./ToggleSelect";
 export { Tooltip, type TooltipProps } from "./Tooltip";