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

package/src/components/Workflow/useWorkflowActions.ts

@@ -0,0 +1,196 @@
+'use client';
+
+import { useCallback, useMemo } from 'react';
+import { useReactFlow, useStoreApi } from '@xyflow/react';
+
+import { createNodeFromType, genId, toDefaultsTranslate } from './createNode';
+import {
+  type AddNodeTarget,
+  FALLBACK_NODE_SIZE,
+  findFreeExit,
+  planNodePlacement,
+} from './placement';
+import { useWorkflow } from './WorkflowContext';
+
+export type { AddNodeTarget } from './placement';
+
+/** What `addNode` did: the new node's id and the auto-connect edge's, if any. */
+export type AddNodeResult = { nodeId: string; edgeId: string | null };
+
+export type AddNodeOptions = {
+  /**
+   * What the inspector does once the new node is selected.
+   * - `'follow'` (default): an open inspector moves to the new node, a closed
+   *   one stays closed — the same rule drag-select follows.
+   * - `'open'`: open it on the new node (what a click does).
+   * - `'close'`: close it, e.g. on a phone where it would cover the canvas.
+   */
+  inspector?: 'follow' | 'open' | 'close';
+};
+
+/** The exit a node added `{ after: nodeId }` would be wired from. */
+export type AddAfterSource = {
+  nodeId: string;
+  sourceHandle: string;
+  /** Display name: the node's instance title, else its type label. */
+  label: string;
+};
+
+export type WorkflowActions = {
+  /**
+   * Add a node of `kind` with the same id and starting config a palette drop
+   * produces, place it per `target` (see `AddNodeTarget`), select it and pan
+   * to it. Node + auto-edge land as one history step, so one undo reverts
+   * both. Returns `null` (and changes nothing) when the editor is read-only,
+   * `kind` is not registered, or the kind's id is taken (a singleton `start`).
+   */
+  addNode: (
+    kind: string,
+    target: AddNodeTarget,
+    options?: AddNodeOptions
+  ) => AddNodeResult | null;
+  /**
+   * The exit `addNode(kind, { after: nodeId })` would wire from, or `null` when
+   * the node has none free — the add would land unconnected at the viewport
+   * centre. Use it to label the action ("Add after ‹label›" vs "Add at
+   * centre"). Whether a given kind then accepts the edge is still up to its
+   * handles and `canConnect`; `addNode`'s `edgeId` reports the outcome.
+   */
+  getAddAfterSource: (
+    nodeId: string | null | undefined
+  ) => AddAfterSource | null;
+  /** `getAddAfterSource(nodeId) !== null`. */
+  canAddAfter: (nodeId: string | null | undefined) => boolean;
+};
+
+/** 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>`.
+ */
+export function useWorkflowActions(): WorkflowActions {
+  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: string | null | undefined): AddAfterSource | null => {
+      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: string | null | undefined) => getAddAfterSource(nodeId) !== null,
+    [getAddAfterSource]
+  );
+
+  const addNode = useCallback(
+    (
+      kind: string,
+      target: AddNodeTarget,
+      { inspector = 'follow' }: AddNodeOptions = {}
+    ): AddNodeResult | null => {
+      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]
+  );
+}

package/src/guidelines/FeedbackActions.mdx

@@ -0,0 +1,133 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Guidelines/Actions in feedback surfaces" />
+
+# Actions in feedback surfaces
+
+Toasts, inline banners, panes and dialogs often need a control: "buy credits",
+"undo", "open file". This page covers which control goes where and how it
+should look.
+
+The test for every case: **does the control look like it belongs to the
+container it sits in?**
+
+> Visual prototype with before/after and a playground:
+> [feedback-actions-proto.apps.mindlogic.tools](https://feedback-actions-proto.apps.mindlogic.tools/)
+> (company login).
+
+---
+
+## Why this exists
+
+Until `Toast` had an `action` prop, callers who wanted a button in a toast put
+a `<Button>` inside `description` and styled it themselves. On the credit-402
+toast in FactChat that produced a neutral outline button (`#494949` text, ink
+hairline) on a rose toast (`#FFE6E8` background, `#69000A` text). It carried
+none of the toast's colors, so it read as a separate card dropped on top.
+
+The fix is one recipe for every toast: the action uses the toast's own text
+color, the same treatment as the close ×.
+
+---
+
+## Rules
+
+### 1. Match the container's weight
+
+Toasts and inline banners carry **text actions**. Buttons belong to surfaces
+that own the space: a pane, a dialog, an empty state.
+
+### 2. The action takes the status color
+
+Inside a tinted container the action uses **that container's text color**
+(`danger.dark` on an error toast, `primary.dark` on an info toast). Never a
+neutral control.
+
+### 3. One action per toast; dismiss is ×
+
+No 「닫기」 or 「취소」 button in a toast; the × already does that. If a
+message needs two actions, it is not a toast; use a dialog or a pane.
+
+### 4. Don't repeat the action in the copy
+
+If the action says 「크레딧 구매」, the message doesn't also say "purchase
+credits to continue". Toast copy stays **within 2 lines**.
+
+### 5. In a pane, the fix is the primary
+
+In a pane or empty state, the action that fixes the problem is the primary
+(ink solid, `colorPalette="neutral" variant="solid"`). Dismiss is outline
+neutral (`colorPalette="neutral" variant="outline"`).
+
+### 6. Toasts with an action stay longer
+
+The reader has to read the message and then decide to act. A toast with an
+action defaults to **8s** instead of 5s. `useToast` does this for you when
+`duration` is not given.
+
+---
+
+## Which control goes where
+
+| Surface            | Primary action                                     | Secondary / dismiss              | Max actions | Copy                                       |
+| ------------------ | -------------------------------------------------- | -------------------------------- | ----------- | ------------------------------------------ |
+| Toast              | Text action in status color, via the `action` prop | × only                           | 1           | ≤ 2 lines, no hint that repeats the action |
+| Inline banner      | Trailing text action in status color               | × if dismissible                 | 1           | 1 line, wraps on mobile                    |
+| Pane / empty state | Ink solid (`neutral` `solid`)                      | Outline neutral                  | 2           | Title + reason + optional hint             |
+| Dialog             | Ink solid, right                                   | Outline neutral, left of primary | 2           | Title + body                               |
+
+---
+
+## Usage
+
+```tsx
+import { useToast } from '@mindlogic-ai/logician-ui';
+
+const showToast = useToast();
+
+showToast({
+  status: 'error',
+  description: '크레딧이 부족해 응답을 생성하지 못했습니다.',
+  action: {
+    label: '크레딧 구매',
+    onClick: openCreditPurchaseModal,
+  },
+  // duration defaults to 8000 because an action is set
+});
+```
+
+- The action renders under the description, aligned with the text column, in
+  the toast's status color with the same hover tint as the ×.
+- Clicking it calls `onClick` and dismisses the toast.
+- `label` accepts any `ReactNode`, but keep it a short verb phrase.
+- An explicit `duration` (including `null` for a persistent toast) always wins.
+- Chakra's own `toaster.create({ action: { label, onClick } })` renders the
+  same way; with that route the label must be a string and the duration
+  default is Chakra's, not 8s.
+
+### Don't: a button inside `description`
+
+```tsx
+// ✗ A neutral control dropped onto a tinted toast; it carries none of the
+//   toast's colors, adds a third line, and dismissal is left to the caller.
+showToast({
+  status: 'error',
+  description: (
+    <>
+      크레딧이 부족합니다. 크레딧을 구매하면 계속 사용할 수 있습니다.
+      <Button colorPalette="neutral" variant="outline" onClick={buy}>
+        크레딧 구매
+      </Button>
+    </>
+  ),
+});
+
+// ✓ One action, in the toast's color, and the copy doesn't repeat it.
+showToast({
+  status: 'error',
+  description: '크레딧이 부족합니다.',
+  action: { label: '크레딧 구매', onClick: buy },
+});
+```
+
+See **Components/Toast → Action / …** for each status and a short-message case.