vultus-core 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "vultus-core",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Framework-neutral action model + hooks for vultus (antd-free by design)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deai-network/unitas.git",
+    "directory": "packages/vultus-core"
+  },
+  "author": "Kristof Csillag <kristof.csillag@deai-labs.com>",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./link": "./src/LinkContext.tsx"
+  },
+  "files": [
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-i18next": ">=15"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "i18next": "^25.0.0",
+    "jsdom": "^29.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-i18next": "^17.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}

package/src/LinkContext.tsx

@@ -0,0 +1,18 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from 'react';
+
+/**
+ * How an internal (`/`-prefixed) markdown link renders. Hosts with a router
+ * inject an SPA link; the default is a full-navigation anchor so router-less
+ * consumers (optio-conversation-ui) work with zero setup.
+ */
+export type InternalLinkComponent = ComponentType<{ href: string; children?: ReactNode }>;
+
+const DefaultInternalLink: InternalLinkComponent = ({ href, children }) => (
+  <a href={href}>{children}</a>
+);
+
+export const InternalLinkContext = createContext<InternalLinkComponent>(DefaultInternalLink);
+
+export function useInternalLink(): InternalLinkComponent {
+  return useContext(InternalLinkContext);
+}

package/src/MessageSink.tsx

@@ -0,0 +1,15 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * How the action framework surfaces an otherwise-unhandled error (no form field,
+ * no inline error target). Default is a no-op so vultus-core stays antd-free and
+ * framework-neutral; vultus-antd's VultusProvider wires this to antd's
+ * message.error. Hosts may inject any toast/notification mechanism.
+ */
+export type MessageSink = (text: string) => void;
+
+export const MessageSinkContext = createContext<MessageSink>(() => {});
+
+export function useMessageSink(): MessageSink {
+  return useContext(MessageSinkContext);
+}

package/src/action-core.ts

@@ -0,0 +1,125 @@
+import type React from 'react';
+import type { MutableRefObject } from 'react';
+import { getVerdict, getReason } from './decision.js';
+import { resolve } from './resolve.js';
+import { routeApiError } from './routeApiError.js';
+import { parseApiError } from './parseApiError.js';
+import type { MessageSink } from './MessageSink.js';
+import type {
+  ActionErrorCtx,
+  ActionOptions,
+  ActionStatus,
+  ConfirmationSpec,
+  Decision,
+  ErrorRoutesRegistry,
+} from './types.js';
+
+/**
+ * Hookless core of the action framework, shared by useAction (single) and
+ * useActionList (dynamic list) so the firing machinery + ActionStatus shape
+ * live in exactly one place — neither entry point reimplements the other.
+ */
+
+export interface ResolvedFields {
+  label: string;
+  icon: React.ReactNode | undefined;
+  variant: 'default' | 'primary' | 'danger';
+  disabled: boolean;
+  reason: string | undefined;
+  invisible: boolean;
+  confirmation: ConfirmationSpec | undefined;
+}
+
+/** Resolve the static (hookless) ActionStatus fields from the options. */
+export function resolveActionFields(opts: ActionOptions<any, any, any>): ResolvedFields {
+  const enabledD = resolve<Decision>(opts.enabled, true);
+  return {
+    label: resolve(opts.label, ''),
+    icon: resolve<React.ReactNode | undefined>(opts.icon, undefined),
+    variant: resolve<'default' | 'primary' | 'danger'>(opts.variant, 'default'),
+    disabled: !getVerdict(enabledD, true),
+    reason: getReason(enabledD),
+    invisible: resolve(opts.invisible, false),
+    confirmation: resolve<ConfirmationSpec | undefined>(opts.confirmation, undefined),
+  };
+}
+
+export interface FirePromiseDeps<RouteId extends string> {
+  disabled: boolean;
+  reason: string | undefined;
+  getPending: () => boolean;
+  setPending: (value: boolean) => void;
+  setErrors: (errors: string[]) => void;
+  errCtxRef: MutableRefObject<ActionErrorCtx | null>;
+  t: (key: string, opts?: Record<string, unknown>) => string;
+  registry?: ErrorRoutesRegistry<RouteId>;
+  messageSink?: MessageSink;
+}
+
+/** Build the async fire (pending guard + error routing) for one action. */
+export function makeFirePromise<TArgs, TResult, RouteId extends string>(
+  opts: ActionOptions<TArgs, TResult, RouteId>,
+  deps: FirePromiseDeps<RouteId>,
+): (args: TArgs) => Promise<void> {
+  return async (args: TArgs) => {
+    if (deps.disabled) {
+      console.warn(`Action '${opts.id}': disabled — ${deps.reason ?? '(no reason)'}`);
+      return;
+    }
+    if (deps.getPending()) {
+      console.warn(`Action '${opts.id}': already pending — ignoring fire`);
+      return;
+    }
+    deps.setErrors([]);
+    deps.setPending(true);
+    try {
+      const result = await opts.fire(args);
+      opts.onSuccess?.(result as TResult);
+    } catch (err) {
+      if (opts.errorRoute && deps.registry) {
+        routeApiError(
+          err,
+          {
+            route: opts.errorRoute,
+            form: deps.errCtxRef.current?.form,
+            setInlineError: deps.errCtxRef.current?.setInlineError,
+            t: deps.t,
+            showError: deps.messageSink,
+          },
+          deps.registry,
+        );
+      }
+      const parsed = parseApiError(err);
+      deps.setErrors([parsed.message ?? 'Action failed']);
+    } finally {
+      deps.setPending(false);
+    }
+  };
+}
+
+/** Assemble the public ActionStatus from resolved fields + state + fire. */
+export function assembleStatus<TArgs>(
+  opts: ActionOptions<TArgs, any, any>,
+  fields: ResolvedFields,
+  pending: boolean,
+  errors: string[],
+  firePromise: (args: TArgs) => Promise<void>,
+): ActionStatus<TArgs> {
+  const fire = (args: TArgs) => {
+    void firePromise(args);
+  };
+  return {
+    id: opts.id,
+    label: fields.label,
+    icon: fields.icon,
+    variant: fields.variant,
+    pending,
+    disabled: fields.disabled,
+    reason: fields.reason,
+    invisible: fields.invisible,
+    confirmation: fields.confirmation,
+    errors,
+    fire: fire as ActionStatus<TArgs>['fire'],
+    firePromise: firePromise as ActionStatus<TArgs>['firePromise'],
+  };
+}

package/src/decision.ts

@@ -0,0 +1,21 @@
+import type { Decision } from './types.js';
+
+export const allow = (reason?: string): Decision => ({ verdict: true, reason });
+export const deny = (reason?: string): Decision => ({ verdict: false, reason });
+export const denyWithReason = (reason: string): Decision => ({ verdict: false, reason });
+
+export const getVerdict = (d: Decision | undefined, fallback: boolean): boolean =>
+  d === undefined ? fallback : typeof d === 'boolean' ? d : d.verdict;
+
+export const getReason = (d: Decision | undefined): string | undefined =>
+  d === undefined ? undefined : typeof d === 'boolean' ? undefined : d.reason;
+
+export const andDecisions = (a: Decision, b: Decision): Decision => {
+  const av = getVerdict(a, false);
+  const bv = getVerdict(b, false);
+  if (av && bv) {
+    const reasons = [getReason(a), getReason(b)].filter(Boolean) as string[];
+    return { verdict: true, reason: reasons.join('; ') || undefined };
+  }
+  return av ? b : a;
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './types.js';
+export * from './decision.js';
+export * from './resolve.js';
+export * from './parseApiError.js';
+export * from './routeApiError.js';
+export { ActionErrorContext, useActionErrorCtx } from './useActionErrorCtx.js';
+export { useAction } from './useAction.js';
+export { useActionList } from './useActionList.js';
+export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
+export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';

package/src/parseApiError.ts

@@ -0,0 +1,11 @@
+import type { ParsedApiError } from './types.js';
+
+export function parseApiError(err: unknown): ParsedApiError {
+  if (typeof err !== 'object' || err === null) return { status: 0 };
+  const e = err as { status?: number; body?: { message?: string; reason?: string } };
+  return {
+    status: e.status ?? 0,
+    reason: e.body?.reason,
+    message: e.body?.message,
+  };
+}

package/src/resolve.ts

@@ -0,0 +1,6 @@
+import type { ValueOrFn } from './types.js';
+
+export function resolve<T>(v: ValueOrFn<T> | undefined, fallback: T): T {
+  if (v === undefined) return fallback;
+  return typeof v === 'function' ? (v as () => T)() : v;
+}

package/src/routeApiError.ts

@@ -0,0 +1,25 @@
+import { parseApiError } from './parseApiError.js';
+import type { ApiErrorContext, ErrorRoutesRegistry } from './types.js';
+
+export function routeApiError<RouteId extends string>(
+  err: unknown,
+  ctx: ApiErrorContext<RouteId>,
+  registry: ErrorRoutesRegistry<RouteId>,
+): void {
+  const parsed = parseApiError(err);
+  const routeMap = registry[ctx.route];
+  const entry = parsed.reason ? routeMap?.[parsed.reason] : undefined;
+  const text = entry?.i18nKey
+    ? ctx.t(entry.i18nKey)
+    : (parsed.message ?? ctx.t('common.error'));
+
+  if (entry?.field && ctx.form) {
+    ctx.form.setFields([{ name: entry.field, errors: [text] }]);
+    return;
+  }
+  if (ctx.setInlineError) {
+    ctx.setInlineError(text);
+    return;
+  }
+  (ctx.showError ?? (() => {}))(text);
+}

package/src/types.ts

@@ -0,0 +1,74 @@
+import type React from 'react';
+import type { MessageSink } from './MessageSink.js';
+
+/**
+ * Minimal structural form contract used by error-routing (antd's FormInstance is
+ * assignable to this). Keeps vultus-core antd-free — see AGENTS.md.
+ */
+export interface FormLike {
+  setFields(fields: { name: string | number | (string | number)[]; errors: string[] }[]): void;
+}
+
+export type Decision = boolean | { verdict: boolean; reason?: string };
+export type ValueOrFn<T> = T | (() => T);
+
+export type ConfirmationSpec =
+  | { kind: 'popconfirm'; question: string }
+  | { kind: 'cascade-modal'; title: string; content: React.ReactNode }
+  | { kind: 'typing'; title: string; entityName: string; description: React.ReactNode };
+
+export interface ActionOptions<TArgs = void, TResult = void, RouteId extends string = string> {
+  id: string;
+  label: ValueOrFn<string>;
+  icon?: ValueOrFn<React.ReactNode>;
+  variant?: ValueOrFn<'default' | 'primary' | 'danger'>;
+  enabled?: ValueOrFn<Decision>;
+  invisible?: ValueOrFn<boolean>;
+  confirmation?: ValueOrFn<ConfirmationSpec | undefined>;
+  errorRoute?: RouteId;
+  fire: (args: TArgs) => Promise<TResult> | TResult;
+  onSuccess?: (result: TResult) => void;
+}
+
+// Conditional rest-tuple lets call sites omit args entirely when TArgs is
+// void (e.g. plain ActionButton click) and requires the value otherwise
+// (e.g. FormSubmitButton passing typed form values).
+type FireArgs<TArgs> = [TArgs] extends [void] ? [] : [args: TArgs];
+
+export interface ActionStatus<TArgs = void> {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  variant: 'default' | 'primary' | 'danger';
+  pending: boolean;
+  disabled: boolean;
+  reason?: string;
+  invisible: boolean;
+  confirmation?: ConfirmationSpec;
+  errors: string[];
+  fire(...args: FireArgs<TArgs>): void;
+  firePromise(...args: FireArgs<TArgs>): Promise<void>;
+}
+
+export type ParsedApiError = {
+  status: number;
+  reason?: string;
+  message?: string;
+};
+
+export type RegistryEntry = { i18nKey: string; field?: string };
+export type ErrorRoutesRegistry<RouteId extends string> =
+  Record<RouteId, Record<string, RegistryEntry>>;
+
+export type ApiErrorContext<RouteId extends string> = {
+  route: RouteId;
+  form?: FormLike;
+  setInlineError?: (text: string | null) => void;
+  t: (key: string) => string;
+  showError?: MessageSink;
+};
+
+export type ActionErrorCtx = {
+  form: FormLike;
+  setInlineError: (text: string | null) => void;
+};

package/src/useAction.ts

@@ -0,0 +1,61 @@
+import { useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useActionErrorCtx } from './useActionErrorCtx.js';
+import { useMessageSink } from './MessageSink.js';
+import { resolveActionFields, makeFirePromise, assembleStatus } from './action-core.js';
+import type { ActionOptions, ActionStatus, ErrorRoutesRegistry } from './types.js';
+
+export function useAction<TArgs = void, TResult = void, RouteId extends string = string>(
+  opts: ActionOptions<TArgs, TResult, RouteId>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): ActionStatus<TArgs> {
+  const errCtx = useActionErrorCtx();
+  const errCtxRef = useRef(errCtx);
+  errCtxRef.current = errCtx;
+  const { t } = useTranslation();
+  const messageSink = useMessageSink();
+
+  const [pending, setPending] = useState(false);
+  const [errors, setErrors] = useState<string[]>([]);
+  const pendingRef = useRef(pending);
+  pendingRef.current = pending;
+
+  const fields = resolveActionFields(opts);
+
+  const firePromise = useMemo(
+    () =>
+      makeFirePromise(opts, {
+        disabled: fields.disabled,
+        reason: fields.reason,
+        getPending: () => pendingRef.current,
+        setPending,
+        setErrors,
+        errCtxRef,
+        t,
+        registry,
+        messageSink,
+      }),
+    [opts, fields.disabled, fields.reason, registry, t, messageSink],
+  );
+
+  // Granular deps by design: memo invalidates on the specific opts/fields
+  // primitives below, not on the whole `opts`/`fields` objects (which are
+  // fresh each render and would defeat the memo).
+  return useMemo<ActionStatus<TArgs>>(
+    () => assembleStatus(opts, fields, pending, errors, firePromise),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      opts.id,
+      fields.label,
+      fields.icon,
+      fields.variant,
+      pending,
+      fields.disabled,
+      fields.reason,
+      fields.invisible,
+      fields.confirmation,
+      errors,
+      firePromise,
+    ],
+  );
+}

package/src/useActionErrorCtx.ts

@@ -0,0 +1,8 @@
+import { createContext, useContext } from 'react';
+import type { ActionErrorCtx } from './types.js';
+
+export const ActionErrorContext = createContext<ActionErrorCtx | null>(null);
+
+export function useActionErrorCtx(): ActionErrorCtx | null {
+  return useContext(ActionErrorContext);
+}

package/src/useActionList.ts

@@ -0,0 +1,58 @@
+import { useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useActionErrorCtx } from './useActionErrorCtx.js';
+import { useMessageSink } from './MessageSink.js';
+import { resolveActionFields, makeFirePromise, assembleStatus } from './action-core.js';
+import type { ActionOptions, ActionStatus, ErrorRoutesRegistry } from './types.js';
+
+/**
+ * Build a DYNAMIC list of actions from a spec array — the list counterpart to
+ * useAction. The hook count is fixed regardless of list length (one shared
+ * error context, one pending/errors map, one memo), so it is usable where
+ * useAction — a per-call hook — cannot be looped (rules of hooks). Pending and
+ * errors are tracked per action id in the shared maps; each action gets real
+ * per-item pending. The firing machinery + ActionStatus shape are the exact
+ * same shared helpers useAction uses (see action-core.ts) — nothing is
+ * reimplemented.
+ */
+export function useActionList<TArgs = void, TResult = void, RouteId extends string = string>(
+  specs: ActionOptions<TArgs, TResult, RouteId>[],
+  registry?: ErrorRoutesRegistry<RouteId>,
+): ActionStatus<TArgs>[] {
+  const errCtx = useActionErrorCtx();
+  const errCtxRef = useRef(errCtx);
+  errCtxRef.current = errCtx;
+  const { t } = useTranslation();
+  const messageSink = useMessageSink();
+
+  const [pendingMap, setPendingMap] = useState<Record<string, boolean>>({});
+  const [errorsMap, setErrorsMap] = useState<Record<string, string[]>>({});
+  const pendingRef = useRef(pendingMap);
+  pendingRef.current = pendingMap;
+
+  return useMemo(
+    () =>
+      specs.map((opts) => {
+        const fields = resolveActionFields(opts);
+        const firePromise = makeFirePromise(opts, {
+          disabled: fields.disabled,
+          reason: fields.reason,
+          getPending: () => !!pendingRef.current[opts.id],
+          setPending: (value) => setPendingMap((m) => ({ ...m, [opts.id]: value })),
+          setErrors: (errs) => setErrorsMap((m) => ({ ...m, [opts.id]: errs })),
+          errCtxRef,
+          t,
+          registry,
+          messageSink,
+        });
+        return assembleStatus(
+          opts,
+          fields,
+          !!pendingMap[opts.id],
+          errorsMap[opts.id] ?? [],
+          firePromise,
+        );
+      }),
+    [specs, pendingMap, errorsMap, registry, t, messageSink],
+  );
+}