@dloizides/ui-feedback
Themable, brand-agnostic React Native (RN-web) feedback components for the dloizides.com portfolio. The components read theme colours and translated copy from a small injectable provider, so each app supplies its own theme + i18n without the package depending on any app's internals.
Components
| Component | Purpose |
|---|---|
ErrorState | Generic error message with an optional retry button. |
EmptyListState | Empty-collection message with an optional navigating call-to-action. |
LoadingFallback | Lightweight spinner for React.lazy / Suspense boundaries. |
PageSkeleton | Shimmer skeleton for full-page loads (list or card variant). |
ConfirmDialog | Modal confirm/cancel dialog with destructive + loading states. |
ToastHost | Transient-toast overlay; pair it with createToastBus(). |
WarmingOverlay | Branded cold-start "warming up…" overlay. |
AppErrorBoundary | Top-level error boundary with a themed, announced fallback. |
Helpers
| Helper | Purpose |
|---|---|
createToastBus() | Framework-agnostic toast emit bus — the ToastHost subscribe port. |
Install
npm install @dloizides/ui-feedback
Peer dependencies: react >= 18, react-native >= 0.74 (use react-native-web on web).
Setup
Mount FeedbackUiProvider once, high in your tree, below your app's own theme
provider. Adapt your local useTheme() + translate helper to the provider:
import { FeedbackUiProvider } from '@dloizides/ui-feedback';
import { useRouter } from 'expo-router';
import { FM } from './localization/helpers';
import { useTheme } from './theme/hooks/useTheme';
const FeedbackUiAdapter = ({ children }: { children: React.ReactNode }) => {
const { theme } = useTheme();
const router = useRouter();
return (
<FeedbackUiProvider theme={theme} t={FM} navigate={(route) => router.push(route)}>
{children}
</FeedbackUiProvider>
);
};
The injected theme only needs colors.{background,surfaceElevated,text,textSecondary,border},
palette.primary['500'] and semantic.error['500'] — any resolved theme with those
fields is structurally compatible.
Usage
import { ErrorState, ConfirmDialog, LoadingFallback } from '@dloizides/ui-feedback';
<ErrorState message="Could not load data" onRetry={refetch} />
<LoadingFallback fullScreen />
<ConfirmDialog
visible={open}
title="Delete item?"
message="This cannot be undone."
destructive
onConfirm={onDelete}
onCancel={() => setOpen(false)}
/>
Toasts — createToastBus()
The toast pipeline is two halves: createToastBus() emits, <ToastHost> renders.
A bus's subscribe is the host's subscribe port.
The bus is framework-agnostic on purpose — no React import, no hook, no provider — so a
React Query mutation callback can raise a toast with no component context in scope. It carries
no styling (ToastHost themes every toast from the provider), and the text you pass is already
localized by you; the bus never sees a translation key.
// src/lib/toastBus.ts — one module-level instance per app
import { createToastBus } from '@dloizides/ui-feedback';
export const toastBus = createToastBus();
// once, in the shell:
<ToastHost subscribe={toastBus.subscribe} />
// anywhere — no provider needed:
useMutation({ onSuccess: () => toastBus.success(FM('menu.saved')) });
toastBus.error(FM('menu.saveFailed'));
toastBus.warning(FM('menu.needsReview'));
toastBus.emit(FM('menu.queued'), 'info'); // explicit type; defaults to 'info'
Emitting with no host mounted is a silent no-op. Every subscriber receives every emit, and
subscribe returns an unsubscribe.
Error boundary — <AppErrorBoundary>
Wrap your app once. The fallback renders through ErrorState, so it themes from the provider,
and it announces itself (role="alert" + accessibilityLiveRegion="assertive").
<AppErrorBoundary
labels={{ title: FM('errorBoundary.title'), message: FM('errorBoundary.message') }}
showDetails={__DEV__}
onError={(error, info) => captureException(error, { extra: { componentStack: info.componentStack } })}
recover={(error) => isChunkLoadError(error) && attemptChunkRecovery()}
onReload={reloadPage}
>
<App />
</AppErrorBoundary>
| Prop | Purpose |
|---|---|
onError(error, info) | Reporting sink (Sentry / logger). Called for every caught error, before recover. |
recover(error) | Return true if handled (e.g. a guarded reload is under way) → shows the updating screen instead of the error screen. |
showDetails | Render the error message in the fallback (dev-only). Default false. |
labels | Partial, pre-localized ErrorBoundaryLabels; anything omitted uses the English defaults in DEFAULT_ERROR_BOUNDARY_LABELS. |
testIDPrefix | Prefix for every testID. Default error-boundary. |
fallback(state) | Escape hatch — replaces the built-in fallback entirely. Receives { error, recovering, retry }. |
onReload | Optional secondary Reload action. The kit never touches window, so you inject the reload. |
The package imports no i18n runtime — localize at the call site and pass strings.
i18n keys
The components call the injected t(key) with these keys (provide them in each app's
locale files): common.retry, common.retryHint, common.confirm, common.cancel,
common.confirmHint, common.cancelHint, loadingFallback.label, loadingFallback.hint,
pageSkeleton.loadingLabel, pageSkeleton.loadingHint. EmptyListState takes its keys as props.
testIDs
Default testIDs (FEEDBACK_TEST_IDS) match the strings the consuming apps already used,
so existing Playwright selectors keep working: error-state, error-state-retry,
empty-list-cta, loading-fallback, page-skeleton, confirm-dialog, confirm-button,
cancel-confirm-button, notification-toast, warming-overlay, error-boundary.
AppErrorBoundary derives its ids from testIDPrefix (default error-boundary), preserving the
selectors the app-local copies used: error-boundary, error-boundary-message,
error-boundary-details, error-boundary-retry-button, error-boundary-reload-button,
error-boundary-updating.
License
MIT