@mindlogic-ai/logician-ui 4.0.0-alpha.36 → 4.0.0-alpha.38

package/dist/components/Workflow/useWorkflowActions.mjs

@@ -0,0 +1,103 @@
+"use client";
+import { useCallback, useMemo } from 'react';
+import { useReactFlow, useStoreApi } from '@xyflow/react';
+import { createNodeFromType, genId, toDefaultsTranslate } from './createNode.mjs';
+import { findFreeExit, planNodePlacement, FALLBACK_NODE_SIZE } from './placement.mjs';
+import { useWorkflow } from './WorkflowContext/WorkflowContext.mjs';
+
+/** Pan duration when `addNode` brings the new node into view. */
+const PAN_MS = 300;
+/**
+ * Imperative editor actions for content rendered inside `<Workflow>` (its
+ * `children` and render slots sit inside the canvas's React Flow provider).
+ * Hosts use this instead of re-implementing node creation and placement — the
+ * tap-to-add palette on touch devices being the first caller.
+ *
+ * Must be called from a component rendered inside `<Workflow>`.
+ */
+function useWorkflowActions() {
+    const { graph, dispatch, getNodeType, translate, hostBridge, readOnly, editor: { drawerTarget }, setSelectedNodeId, setSelectedEdgeId, setDrawerTarget, } = useWorkflow();
+    const { getNode, getViewport, setCenter } = useReactFlow();
+    const store = useStoreApi();
+    const getAddAfterSource = useCallback((nodeId) => {
+        const exit = findFreeExit(graph, getNodeType, nodeId);
+        if (!exit)
+            return null;
+        const def = getNodeType(exit.node.kind);
+        const label = def?.getInstanceTitle?.(exit.node.config) || def?.label || exit.node.id;
+        return { nodeId: exit.node.id, sourceHandle: exit.sourceHandle, label };
+    }, [graph, getNodeType]);
+    const canAddAfter = useCallback((nodeId) => getAddAfterSource(nodeId) !== null, [getAddAfterSource]);
+    const addNode = useCallback((kind, target, { inspector = 'follow' } = {}) => {
+        if (readOnly)
+            return null;
+        const def = getNodeType(kind);
+        if (!def)
+            return null;
+        const draft = createNodeFromType(def, {
+            position: { x: 0, y: 0 },
+            nodes: graph.nodes,
+            translate: toDefaultsTranslate(translate),
+            hostBridge,
+        });
+        // `nextNodeId` returns a fixed id for singletons (`start`); a second one
+        // would be dropped by the reducer's dedupe, so report it instead.
+        if (graph.nodes.some((n) => n.id === draft.id))
+            return null;
+        // Centre of the visible pane, in flow coordinates.
+        const { width, height } = store.getState();
+        const viewport = getViewport();
+        const viewportCenter = {
+            x: (width / 2 - viewport.x) / viewport.zoom,
+            y: (height / 2 - viewport.y) / viewport.zoom,
+        };
+        const { position, edge } = planNodePlacement({
+            graph,
+            getNodeType,
+            node: draft,
+            target,
+            viewportCenter,
+            edgeId: genId('e'),
+            getNodeSize: (id) => {
+                const { width: w, height: h } = getNode(id)?.measured ?? {};
+                return w && h ? { width: w, height: h } : undefined;
+            },
+        });
+        const node = { ...draft, position };
+        dispatch({
+            type: 'addNodeWithEdge',
+            node,
+            autoConnectFrom: edge ? { edge } : null,
+        });
+        // Select the new node so a follow-up `{ after: selected }` chains on.
+        setSelectedNodeId(node.id);
+        setSelectedEdgeId(null);
+        if (inspector === 'open' || (inspector === 'follow' && drawerTarget)) {
+            setDrawerTarget({ type: 'node', id: node.id });
+        }
+        else if (inspector === 'close') {
+            setDrawerTarget(null);
+        }
+        void setCenter(position.x + FALLBACK_NODE_SIZE.width / 2, position.y + FALLBACK_NODE_SIZE.height / 2, { zoom: viewport.zoom, duration: PAN_MS });
+        return { nodeId: node.id, edgeId: edge?.id ?? null };
+    }, [
+        readOnly,
+        getNodeType,
+        graph,
+        translate,
+        hostBridge,
+        store,
+        getViewport,
+        getNode,
+        dispatch,
+        setSelectedNodeId,
+        setSelectedEdgeId,
+        drawerTarget,
+        setDrawerTarget,
+        setCenter,
+    ]);
+    return useMemo(() => ({ addNode, getAddAfterSource, canAddAfter }), [addNode, getAddAfterSource, canAddAfter]);
+}
+
+export { useWorkflowActions };
+//# sourceMappingURL=useWorkflowActions.mjs.map

package/dist/components/Workflow/useWorkflowActions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWorkflowActions.mjs","sources":["../../../src/components/Workflow/useWorkflowActions.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/index.js

@@ -173,6 +173,7 @@ var NodeShell_styles = require('./components/Workflow/canvas/NodeShell/NodeShell
 var workflowLabelProps = require('./components/Workflow/canvas/workflowLabelProps.js');
 var graphObserver = require('./components/Workflow/graphObserver.js');
 var graphReducer = require('./components/Workflow/graphReducer.js');
+var useWorkflowActions = require('./components/Workflow/useWorkflowActions.js');
 var Workflow = require('./components/Workflow/Workflow.js');
 var Workflow_types = require('./components/Workflow/Workflow.types.js');
 var WorkflowContext = require('./components/Workflow/WorkflowContext/WorkflowContext.js');
@@ -382,6 +383,9 @@ exports.TagCloseButton = TagCloseButton.TagCloseButton;
 exports.TagLabel = TagLabel.TagLabel;
 exports.Textarea = Textarea.Textarea;
 exports.Toast = Toast.Toast;
+exports.TOAST_ACTION_DURATION = Toast_styles.TOAST_ACTION_DURATION;
+exports.TOAST_DEFAULT_DURATION = Toast_styles.TOAST_DEFAULT_DURATION;
+exports.actionStyles = Toast_styles.actionStyles;
 exports.closeButtonStyles = Toast_styles.closeButtonStyles;
 exports.toastStyles = Toast_styles.toastStyles;
 exports.Toaster = Toaster.Toaster;
@@ -424,6 +428,7 @@ exports.WorkflowGraphObserverContext = graphObserver.WorkflowGraphObserverContex
 exports.useWorkflowGraphObserver = graphObserver.useWorkflowGraphObserver;
 exports.emptyGraph = graphReducer.emptyGraph;
 exports.graphReducer = graphReducer.graphReducer;
+exports.useWorkflowActions = useWorkflowActions.useWorkflowActions;
 exports.Workflow = Workflow.Workflow;
 exports.defineNodeType = Workflow_types.defineNodeType;
 exports.resolveDefaultConfig = Workflow_types.resolveDefaultConfig;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.mjs

@@ -138,7 +138,7 @@ export { TagCloseButton } from './components/Tag/TagCloseButton/TagCloseButton.m
 export { TagLabel } from './components/Tag/TagLabel/TagLabel.mjs';
 export { Textarea } from './components/Textarea/Textarea.mjs';
 export { Toast } from './components/Toast/Toast.mjs';
-export { closeButtonStyles, toastStyles } from './components/Toast/Toast.styles.mjs';
+export { TOAST_ACTION_DURATION, TOAST_DEFAULT_DURATION, actionStyles, closeButtonStyles, toastStyles } from './components/Toast/Toast.styles.mjs';
 export { Toaster, toaster } from './components/Toast/Toaster.mjs';
 export { useToast } from './components/Toast/useToast.mjs';
 export { Tooltip } from './components/Tooltip/Tooltip.mjs';
@@ -171,6 +171,7 @@ export { CARD_WIDTH, MAX_META_CHIPS, PORT_STYLE, metaChipStyles } from './compon
 export { workflowLabelProps } from './components/Workflow/canvas/workflowLabelProps.mjs';
 export { WorkflowGraphObserverContext, useWorkflowGraphObserver } from './components/Workflow/graphObserver.mjs';
 export { emptyGraph, graphReducer } from './components/Workflow/graphReducer.mjs';
+export { useWorkflowActions } from './components/Workflow/useWorkflowActions.mjs';
 export { Workflow } from './components/Workflow/Workflow.mjs';
 export { defineNodeType, resolveDefaultConfig } from './components/Workflow/Workflow.types.mjs';
 export { WorkflowProvider, useWorkflow, useWorkflowTranslate } from './components/Workflow/WorkflowContext/WorkflowContext.mjs';

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindlogic-ai/logician-ui",
-  "version": "4.0.0-alpha.36",
+  "version": "4.0.0-alpha.38",
   "description": "A comprehensive React design system built on Chakra UI",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/components/Toast/Toast.action.test.tsx

@@ -0,0 +1,135 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { system } from '@/theme';
+
+import { TOAST_ACTION_DURATION, TOAST_DEFAULT_DURATION } from './Toast.styles';
+import type { UseToastOptions } from './Toast.types';
+import { Toaster, toaster } from './Toaster';
+import { useToast } from './useToast';
+
+let showToast: ReturnType<typeof useToast>;
+
+const Harness = () => {
+  showToast = useToast();
+  return null;
+};
+
+const renderToaster = () =>
+  render(
+    <ChakraProvider value={system}>
+      <Toaster />
+      <Harness />
+    </ChakraProvider>
+  );
+
+const fire = (options: UseToastOptions) => {
+  let id = '';
+  act(() => {
+    id = showToast(options);
+  });
+  return id;
+};
+
+afterEach(() => {
+  act(() => {
+    toaster.remove();
+  });
+  vi.restoreAllMocks();
+});
+
+describe('Toast action', () => {
+  it('renders the action as a named button under the description', async () => {
+    renderToaster();
+    fire({
+      status: 'error',
+      description: '크레딧이 부족합니다.',
+      action: { label: '크레딧 구매', onClick: () => {} },
+    });
+
+    const action = await screen.findByRole('button', { name: '크레딧 구매' });
+    expect(action).toHaveAttribute('type', 'button');
+    // Exactly one action besides the close ×.
+    expect(screen.getAllByRole('button')).toHaveLength(2);
+  });
+
+  it('calls onClick once and dismisses the toast', async () => {
+    renderToaster();
+    const onClick = vi.fn();
+    fire({
+      status: 'error',
+      description: '크레딧이 부족합니다.',
+      action: { label: '크레딧 구매', onClick },
+    });
+
+    const action = await screen.findByRole('button', { name: '크레딧 구매' });
+    const root = action.closest('[data-scope="toast"][data-part="root"]');
+    expect(root).toHaveAttribute('data-state', 'open');
+
+    fireEvent.click(action);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    // Dismissed: the root leaves the open state (exit animation follows).
+    await waitFor(() => expect(root).toHaveAttribute('data-state', 'closed'));
+  });
+
+  it("accepts Chakra's own toaster.create({ action }) without double-calling", async () => {
+    renderToaster();
+    const onClick = vi.fn();
+    act(() => {
+      toaster.create({
+        type: 'info',
+        description: 'Exported.',
+        action: { label: 'Open', onClick },
+      });
+    });
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Open' }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders no action button when none is given', async () => {
+    renderToaster();
+    fire({ status: 'success', description: 'Saved.' });
+
+    await screen.findByText('Saved.');
+    expect(screen.getAllByRole('button')).toHaveLength(1); // close × only
+  });
+});
+
+describe('useToast duration', () => {
+  const durationOf = (options: UseToastOptions) => {
+    const create = vi.spyOn(toaster, 'create');
+    fire(options);
+    return create.mock.calls.at(-1)?.[0].duration;
+  };
+
+  it('defaults to 5s without an action', () => {
+    renderToaster();
+    expect(durationOf({ description: 'Saved.' })).toBe(TOAST_DEFAULT_DURATION);
+  });
+
+  it('defaults to 8s with an action', () => {
+    renderToaster();
+    expect(
+      durationOf({
+        description: 'Deleted.',
+        action: { label: 'Undo', onClick: () => {} },
+      })
+    ).toBe(TOAST_ACTION_DURATION);
+  });
+
+  it("keeps the caller's duration, including null", () => {
+    renderToaster();
+    const action = { label: 'Undo', onClick: () => {} };
+    expect(durationOf({ description: 'a', action, duration: 3000 })).toBe(3000);
+    expect(durationOf({ description: 'b', action, duration: null })).toBe(null);
+  });
+});

package/src/components/Toast/Toast.stories.tsx

@@ -4,6 +4,7 @@ import { useState } from 'react';
 
 import { Button } from '../Button';
 import { Toast } from './Toast';
+import type { UseToastOptions } from './Toast.types';
 import { Toaster } from './Toaster';
 import { useToast } from './useToast';
 
@@ -481,3 +482,113 @@ export const RapidFire: Story = {
     );
   },
 };
+
+/**
+ * Toasts with an action.
+ *
+ * The action is a text action in the toast's own status color, under the
+ * description and aligned with it — not a neutral `<Button>` inside
+ * `description`. One action per toast; dismiss stays on the ×. A toast with
+ * an action stays for 8s unless `duration` is given.
+ *
+ * See "Guidelines/Actions in feedback surfaces".
+ */
+const ActionStory = ({
+  label,
+  options,
+}: {
+  label: string;
+  /** Builds the toast options; `fired` reports a click back to the story */
+  options: (fired: (message: string) => () => void) => UseToastOptions;
+}) => {
+  const showToast = useToast();
+  const [log, setLog] = useState<string | null>(null);
+  const fired = (message: string) => () => setLog(`onClick: ${message}`);
+
+  return (
+    <>
+      <Toaster />
+      <Stack gap={3} align="center">
+        <Button onClick={() => showToast(options(fired))}>{label}</Button>
+        {log && (
+          <Text fontSize="sm" color="fg.muted">
+            {log}
+          </Text>
+        )}
+      </Stack>
+    </>
+  );
+};
+
+export const ActionError: Story = {
+  name: 'Action / Error',
+  render: () => (
+    <ActionStory
+      label="Show error toast with action"
+      options={(fired) => ({
+        status: 'error',
+        description:
+          '크레딧이 부족해 응답을 생성하지 못했습니다. 이번 달 남은 크레딧: 0',
+        action: { label: '크레딧 구매', onClick: fired('크레딧 구매') },
+      })}
+    />
+  ),
+};
+
+export const ActionWarning: Story = {
+  name: 'Action / Warning',
+  render: () => (
+    <ActionStory
+      label="Show warning toast with action"
+      options={(fired) => ({
+        status: 'warning',
+        title: '모델 지원 종료',
+        description: '이 채팅의 모델이 지원 종료되어 기본 모델로 바뀌었습니다.',
+        action: { label: '모델 선택', onClick: fired('모델 선택') },
+      })}
+    />
+  ),
+};
+
+export const ActionInfo: Story = {
+  name: 'Action / Info',
+  render: () => (
+    <ActionStory
+      label="Show info toast with action"
+      options={(fired) => ({
+        status: 'info',
+        description: '내보내기가 끝났습니다. 파일을 다운로드할 수 있습니다.',
+        action: { label: '파일 열기', onClick: fired('파일 열기') },
+      })}
+    />
+  ),
+};
+
+export const ActionSuccess: Story = {
+  name: 'Action / Success',
+  render: () => (
+    <ActionStory
+      label="Show success toast with action"
+      options={(fired) => ({
+        status: 'success',
+        title: '업로드 완료',
+        description: '문서 3개를 프로젝트에 추가했습니다.',
+        action: { label: '프로젝트 보기', onClick: fired('프로젝트 보기') },
+      })}
+    />
+  ),
+};
+
+export const ActionShortMessage: Story = {
+  name: 'Action / Short message',
+  render: () => (
+    <ActionStory
+      label="Show short toast with undo"
+      options={(fired) => ({
+        status: 'success',
+        description: '채팅을 삭제했습니다.',
+        action: { label: '되돌리기', onClick: fired('되돌리기') },
+      })}
+    />
+  ),
+};

package/src/components/Toast/Toast.styles.ts

@@ -62,3 +62,63 @@ export const closeButtonStyles: Record<ToastStatus, BoxProps> = {
     },
   },
 };
+
+/**
+ * Action styles for each toast status.
+ *
+ * A toast's action is a text action in the toast's own text color — the same
+ * palette as `toastStyles[status].color` — with the hover tint of the close ×.
+ * No border and no fill: a neutral or outlined button inside a tinted toast
+ * reads as a separate card dropped on top of it.
+ *
+ * `ml: -2` cancels the horizontal padding so the label lines up with the
+ * description text above it.
+ */
+const actionBase: BoxProps = {
+  fontWeight: 'bold',
+  px: 2,
+  py: 1,
+  ml: -2,
+  height: 'auto',
+  alignSelf: 'flex-start',
+  borderRadius: 'sm',
+  borderWidth: 0,
+  bg: 'transparent',
+  cursor: 'pointer',
+};
+
+export const actionStyles: Record<ToastStatus, BoxProps> = {
+  info: {
+    ...actionBase,
+    color: 'primary.dark',
+    _hover: { bg: 'primary.lighter' },
+    _focusVisible: { outline: '2px solid', outlineColor: 'primary.dark' },
+  },
+  warning: {
+    ...actionBase,
+    color: 'warning.dark',
+    _hover: { bg: 'warning.lighter' },
+    _focusVisible: { outline: '2px solid', outlineColor: 'warning.dark' },
+  },
+  success: {
+    ...actionBase,
+    color: 'success.dark',
+    _hover: { bg: 'success.lighter' },
+    _focusVisible: { outline: '2px solid', outlineColor: 'success.dark' },
+  },
+  error: {
+    ...actionBase,
+    color: 'danger.dark',
+    _hover: { bg: 'danger.lighter' },
+    _focusVisible: { outline: '2px solid', outlineColor: 'danger.dark' },
+  },
+};
+
+/** Default duration (ms) of a toast without an action, when none is given */
+export const TOAST_DEFAULT_DURATION = 5000;
+
+/**
+ * Default duration (ms) of a toast that carries an action, when none is given.
+ * The reader needs time to read the message *and* decide to act.
+ */
+export const TOAST_ACTION_DURATION = 8000;

package/src/components/Toast/Toast.tsx

@@ -1,20 +1,25 @@
 import { Flex, Stack, Toast as ChakraToast } from '@chakra-ui/react';
 
-import { closeButtonStyles } from './Toast.styles';
+import { actionStyles, closeButtonStyles } from './Toast.styles';
 import { ToastProps } from './Toast.types';
 import { ToastIcon } from './ToastIcon/ToastIcon';
 
 /**
  * Toast component using Chakra UI v3 composition pattern
  *
- * Uses Toast.Root, Toast.Title, Toast.Description, and Toast.CloseTrigger
- * for better composition and customization.
+ * Uses Toast.Root, Toast.Title, Toast.Description, Toast.ActionTrigger and
+ * Toast.CloseTrigger for better composition and customization.
+ *
+ * `action` renders under the description as a text action in the status
+ * color, aligned with the text column. Don't put a `<Button>` in
+ * `description` — use `action`.
  */
 export const Toast = ({
   title,
   description,
   status = 'success',
   onClose,
+  action,
   ...rest
 }: ToastProps) => (
   <ChakraToast.Root
@@ -39,6 +44,14 @@ export const Toast = ({
             {description}
           </ChakraToast.Description>
         )}
+        {action && (
+          <ChakraToast.ActionTrigger
+            onClick={action.onClick}
+            {...(actionStyles[status] as any)}
+          >
+            {action.label}
+          </ChakraToast.ActionTrigger>
+        )}
       </Stack>
     </Flex>
     <ChakraToast.CloseTrigger

package/src/components/Toast/Toast.types.ts

@@ -12,6 +12,21 @@ import {
  */
 export type ToastStatus = 'info' | 'warning' | 'success' | 'error';
 
+/**
+ * The single action a toast can carry.
+ *
+ * Rendered as a text action in the toast's status color, under the
+ * description. Clicking it calls `onClick` and dismisses the toast.
+ * One action per toast — dismiss is the ×, never a second action.
+ * See the "Guidelines/Actions in feedback surfaces" page in Storybook.
+ */
+export interface ToastAction {
+  /** Action label — keep it to a short verb phrase ("크레딧 구매", "Undo") */
+  label: ReactNode;
+  /** Called when the action is clicked; the toast is dismissed afterwards */
+  onClick: () => void;
+}
+
 /**
  * Toast component props
  * Uses ToastRootProps as base and overrides title for ReactNode support
@@ -25,15 +40,23 @@ export interface ToastProps extends Omit<ToastRootProps, 'title'> {
   status?: ToastStatus;
   /** Custom close handler */
   onClose?: () => void;
+  /** One action, rendered as a text action in the status color */
+  action?: ToastAction;
 }
 
 /**
  * Options for useToast hook
  * Extends Chakra's ToastOptions with custom properties
  */
-export interface UseToastOptions extends ToastOptions {
+export interface UseToastOptions extends Omit<ToastOptions, 'action'> {
   /** Toast status - restricted to common statuses */
   status?: ToastStatus;
+  /**
+   * One action, rendered as a text action in the status color.
+   * Unlike Chakra's `action`, the label accepts any ReactNode.
+   * When set and `duration` is not given, the toast stays for 8s instead of 5s.
+   */
+  action?: ToastAction;
   /** Custom styles to apply to the toast */
   styles?: BoxProps;
 }
@@ -47,6 +70,8 @@ export interface ToasterCreateOptions extends ToastOptions {
   meta?: {
     /** Custom close handler for the toast */
     onClose?: () => void;
+    /** Toast action (ReactNode label); takes precedence over Chakra's `action` */
+    action?: ToastAction;
     /** Custom styles to merge with default toast styles */
     styles?: BoxProps;
     /** Allow additional custom metadata */

package/src/components/Toast/Toaster.tsx

@@ -7,6 +7,7 @@ import {
 
 import { Toast } from './Toast';
 import { toastStyles } from './Toast.styles';
+import type { ToastAction } from './Toast.types';
 
 /**
  * Global toaster instance for managing toast notifications
@@ -61,6 +62,15 @@ export const Toaster = () => (
         // Extract custom data from meta
         const customStyles = toast.meta?.styles || {};
         const onClose = toast.meta?.onClose;
+        // `useToast` passes the action through meta so its label can be a
+        // ReactNode. A plain `toaster.create({ action })` (Chakra's own option)
+        // also works: Toast.ActionTrigger already calls `toast.action.onClick`
+        // itself, so the handler passed down here must not call it again.
+        const action: ToastAction | undefined =
+          toast.meta?.action ??
+          (toast.action
+            ? { label: toast.action.label, onClick: () => {} }
+            : undefined);
 
         return (
           <Toast
@@ -68,6 +78,7 @@ export const Toaster = () => (
             description={toast.description}
             status={toast.type}
             onClose={onClose}
+            action={action}
             {...toastStyles[toast.type as keyof typeof toastStyles]}
             {...customStyles}
           />

package/src/components/Toast/useToast.tsx

@@ -1,6 +1,10 @@
 import { useRef } from 'react';
 
-import { toastStyles } from './Toast.styles';
+import {
+  TOAST_ACTION_DURATION,
+  TOAST_DEFAULT_DURATION,
+  toastStyles,
+} from './Toast.styles';
 import {
   ToasterCreateOptions,
   ToastStatusChangeDetails,
@@ -22,9 +26,19 @@ export const useToast = () => {
     title,
     description,
     styles: stylesProp,
-    duration = 5000,
+    duration: durationProp,
+    action,
     ...rest
   }: UseToastOptions) => {
+    // A toast with an action stays longer, unless the caller chose a duration
+    // (including `null` / `Infinity` for a persistent toast).
+    const duration =
+      durationProp !== undefined
+        ? durationProp
+        : action
+          ? TOAST_ACTION_DURATION
+          : TOAST_DEFAULT_DURATION;
+
     // NOTE: placement is not supported - must be configured in Toaster.tsx createToaster()
     const styles = {
       ...toastStyles[status],
@@ -49,6 +63,7 @@ export const useToast = () => {
       meta: {
         // Pass custom data through meta
         styles, // for custom toast style
+        action, // ReactNode label, so it travels in meta rather than `action`
         onClose: () => toaster.dismiss(toastId), // Custom close handler
       },
       onStatusChange: (details: ToastStatusChangeDetails) => {