@dumanarge/xsweb-shared-lib

Shared frontend library for DumanArge IoT Platform React applications.

Provides production-ready UI kits for authentication, data tables, error handling, and schema-driven forms. Built on shadcn/ui conventions — the host app supplies the actual UI primitives via @/components/ui/*.

Installation

pnpm add @dumanarge/xsweb-shared-lib

Peer Dependencies

Install the peer dependencies used by the kits you need:

# Required
pnpm add react react-dom zod react-hook-form @hookform/resolvers

# auth-kit
pnpm add react-i18next lucide-react sonner

# datatable-kit
pnpm add @tanstack/react-table @radix-ui/react-icons react-i18next lucide-react

# errors-kit — no extra peers

# form-kit — no extra peers (zod + react-hook-form already listed above)

Kits

auth-kit

What it does: Ready-made forms and page content for sign-in, forgot password, reset password, and OTP. Router-agnostic; wired via callbacks (onLogin, onNavigate, etc.).

• AuthKitProvider / useAuthKit — Provides config (callbacks, paths, logo, i18n).
• SignInForm, ForgotPasswordForm, ResetPasswordForm, OtpForm — Form components (react-hook-form + zod).
• SignInPageContent, SignIn2PageContent, ForgotPasswordPageContent, ResetPasswordPageContent, OtpPageContent — Layout + form content (logo, card, copy).
• defaultTranslations, useAuthKitTranslation — Auth strings (en/tr) and translation hook.
• IconApple, IconGmail, IconFacebook, IconGithub — Social login icons.
• OAuth URL helpers (buildGoogleAuthUrl, buildAppleAuthUrl) are included.

import { AuthKitProvider, SignInPageContent } from '@dumanarge/xsweb-shared-lib/auth-kit';

<AuthKitProvider
  onLogin={async (email, password) => { /* API */ }}
  onNavigate={(path) => navigate(path)}
  signInPath="/sign-in"
  forgotPasswordPath="/forgot-password"
>
  <SignInPageContent />
</AuthKitProvider>

datatable-kit

What it does: TanStack Table–based data table components with sorting, filtering, pagination, URL state, and optional Excel import/export.

• DataTable — Main table; search, filters, pagination, row/bulk actions, optional Excel.
• createSelectionColumn, DataTableColumnHeader, DataTableFacetedFilter, DataTableViewOptions, DataTablePagination, DataTableToolbar, DataTableBulkActions — Selection column, header, faceted filter, view options, pagination, toolbar, bulk actions bar.
• useTableUrlState — Keeps filter and page state in the URL (bookmarkable / shareable).
• getPageNumbers, exportToExcel, getExportData, parseExcelFile — Page number helpers and Excel utilities.

Types: DataTableConfig, FilterConfig, ExcelConfig, UrlStateConfig, etc.

import { DataTable, createSelectionColumn } from '@dumanarge/xsweb-shared-lib/datatable-kit';

const columns = [
  createSelectionColumn(),
  { accessorKey: 'name', header: 'Name' },
  // ...
];
<DataTable data={rows} columns={columns} search={{ placeholder: 'Search...' }} />

errors-kit

What it does: Error code → page component mapping and global API/Query error handling (toast, redirect, modal).

• ErrorsKitProvider / useErrorsKit — Provides errorMap (code → React component) and optional defaultErrorComponent.
• ErrorRenderer — Renders the matching error page from the URL/param error code (404, 403, etc.).
• createErrorHandler, useErrorHandler — Handles Axios/TanStack Query errors by severity (toast / redirect / reload / modal). Configured via levelForStatus, levelForCode, levelActions, statusToSlug, onRedirect, onToast, on401, onCritical.
• defaultLevelForStatus, defaultStatusToSlug, defaultLevelActions — Default mapping values.

import { ErrorsKitProvider, createErrorHandler, ErrorRenderer } from '@dumanarge/xsweb-shared-lib/errors-kit';

const errorMap = { 'not-found': NotFoundPage, 'forbidden': ForbiddenPage };
const handler = createErrorHandler({ onToast: toast.error, onRedirect: navigate });

<ErrorsKitProvider errorMap={errorMap} handlerConfig={{ onToast, onRedirect, ... }}>
  <ErrorRenderer errorCode={errorCodeFromUrl} />
</ErrorsKitProvider>

form-kit

What it does: Schema-driven form layer built on react-hook-form + zod: generates forms from field configs (field config + zod schema).

• FormKitProvider / useFormKit — Default layout and field type → component mapping (optional).
• SchemaForm, FieldRenderer — Renders forms from schema; uses host Form, FormField, Input, Select, etc.
• useSchemaForm — Builds zod schema from fields + refines and wires react-hook-form via zodResolver.
• buildSchema — Produces a single zod schema from field validations and cross-field refines.
• createRefine, getPasswordStrengthRefines, getPasswordConfirmRefines — Refine factories (equality, password strength, confirm).

Types: FieldConfig, RefineConfig, FormComponents, SchemaFormProps, etc.

import { SchemaForm, getPasswordConfirmRefines } from '@dumanarge/xsweb-shared-lib/form-kit';

const fields = [
  { name: 'email', label: 'Email', type: 'email', validation: z.string().email() },
  { name: 'password', label: 'Password', type: 'password', validation: z.string().min(8) },
  { name: 'confirmPassword', label: 'Confirm', type: 'password', validation: z.string() },
];
const refines = getPasswordConfirmRefines({
  passwordPath: 'password',
  confirmPath: 'confirmPassword',
  message: "Passwords don't match",
});

<SchemaForm
  components={formComponents}
  fields={fields}
  refines={refines}
  defaultValues={{ email: '', password: '', confirmPassword: '' }}
  onSubmit={handleSubmit}
/>

Sub-path Imports

Import kits directly to keep your bundle lean:

import { AuthKitProvider, SignInForm } from '@dumanarge/xsweb-shared-lib/auth-kit';
import { DataTable } from '@dumanarge/xsweb-shared-lib/datatable-kit';
import { ErrorsKitProvider, createErrorHandler } from '@dumanarge/xsweb-shared-lib/errors-kit';
import { SchemaForm, useSchemaForm } from '@dumanarge/xsweb-shared-lib/form-kit';

Host App Requirements

This library expects the host app to provide shadcn/ui-style components via @/components/ui/* path alias. The required component modules are declared in src/externals.d.ts:

@/lib/utils (cn), @/components/ui/button, @/components/ui/input, @/components/ui/form, @/components/ui/card, @/components/ui/input-otp, @/components/password-input, @/components/ui/badge, @/components/ui/separator, @/components/ui/tooltip, @/components/ui/dropdown-menu, @/components/ui/table, @/components/ui/select, @/components/ui/command, @/components/ui/popover, @/components/ui/checkbox.

Requirements

• Node.js >= 20
• TypeScript >= 5.7
• React >= 18
• Zod ^3.22.0 or ^4.0.0 (auth-kit, form-kit)

License

MIT