@mantis-core/next-core

Reusable Next.js app-level providers for Mantis Core apps.

Docs

Full LLM-oriented documentation ships in the package tarball under docs/:

• docs/providers.md — MantisCoreBaseProvider (query client, session, PrimeReact, toaster wiring).
• docs/theme.md — ./theme subpath: MantisThemeProvider, preset/color-ramp/severity theming, field-config axis, persistence.
• docs/toasts.md — MantisToaster + useMantisToasts.
• docs/hooks.md — ./hooks subpath: useList/useOne/useCreate/useUpdate/useDelete over the runAction (ResultWrapper<T>) contract.
• docs/setup.md — install + provider composition + styles + a minimal form/table recipe.

Scope

• Query client creation.
• Session provider wiring.
• PrimeReact provider wiring.
• Toast provider wiring.
• PrimeReact 11 theme + form field-config provider (./theme subpath).
• TanStack Query data hooks over the shared runAction contract (./hooks subpath).

Out Of Scope

• Route/page business logic.
• Domain data fetching.
• UI components outside provider concerns.

Public API

createMantisCoreQueryClient(): QueryClient

type MantisCoreBaseProviderProps = PropsWithChildren<{
  includeSessionProvider?: boolean;
  includeToaster?: boolean;
  queryClient?: QueryClient;
}>;

MantisCoreBaseProvider(props)

type UseMantisToasts = {
  addSuccessToast(...)
  addErrorToast(...)
  addInfoToast(...)
  addWarningToast(...)
  addLoadingToast(...)
  promiseToast(...)
  jsxToast(...)
  dismiss(...)
  remove(...)
}

useMantisToasts(): UseMantisToasts

Theme (@mantis-core/next-core/theme)

See docs/theme.md for the full contract (gotchas, persistence, buildPreset).

MantisThemeProvider(props: { initialConfig?: DeepPartial<MantisConfig>; onChange?: (config: MantisConfig) => void; license?: string })

useMantisTheme(): MantisThemeConfig & { setTheme(patch: Partial<MantisThemeConfig>): void }
useMantisConfigController(): { config: MantisConfig; setConfig; setTheme; setFields }
useFieldConfig(): MantisFieldConfig
useFieldConfigController(): { config: MantisFieldConfig; setFields }
useLocalStorageConfig(key: string): { initialConfig: DeepPartial<MantisConfig> | undefined; onChange: (config: MantisConfig) => void }

BASE_PRESETS, PRIMARY_RAMPS, SURFACE_RAMPS, DEFAULT_PRIMARY_RAMP, DEFAULT_SURFACE_RAMP
buildPreset(preset, primary, surface, severities?)
DEFAULT_MANTIS_CONFIG, resolveConfig(partial?), serializeConfig(config), deserializeConfig(raw), deepMerge(base, patch)

Hooks (@mantis-core/next-core/hooks)

See docs/hooks.md for the full contract.

useList<T>(key, fetcher, options?)
useOne<T>(key, id, fetcher, options?)
useCreate<TData, TInput>(action, options?)
useUpdate<TData, TInput>(action, options?)
useDelete<TData, TInput>(action, options?)

Usage Example

"use client";

import { MantisCoreBaseProvider } from "@mantis-core/next-core";

export default function Providers({ children }: { children: React.ReactNode }) {
  return <MantisCoreBaseProvider>{children}</MantisCoreBaseProvider>;
}

"use client";

import { useMantisToasts } from "@mantis-core/next-core";

export function Example() {
  const toast = useMantisToasts();
  return <button onClick={() => toast.addSuccessToast("Guardado")}>Toast</button>;
}

Provider Behavior

• Creates a default QueryClient unless one is injected.
• Wraps children with PrimeReactProvider.
• Optionally includes SessionProvider.
• Optionally includes MantisToaster, the native PrimeReact 11 toast host.
• Toast colors come entirely from the active PR11 preset (severity tokens) — no custom CSS.

Build

pnpm --filter @mantis-core/next-core build
pnpm --filter @mantis-core/next-core typecheck

Peer Dependencies

This package expects the consuming app to provide:

• react, react-dom
• next-auth
• @tanstack/react-query
• primereact
• @primereact/ui