@worktif/purei

Enterprise-grade React UI foundation: opinionated MUI theme provider, component customizations, and ready-to-use UI primitives for building resilient, accessible, and performant applications.

Overview

@worktif/purei is a production-ready UI utility package for React 19 + MUI 7. It delivers:

• A hardened theme provider with dark/light mode, custom color schemes, typography, and elevation.
• Enterprise-ready component customizations focused on accessibility, consistency, and predictable behavior.
• A curated set of styled UI components (buttons, cards, alerts, loaders, tooltips, containers, headers, lists, badges, etc.).
• Practical state utilities for dialogs and forms (context + hooks) with validation and internationalization seams.

It exists to standardize visual language and UI behaviors across large applications, reduce design drift, and accelerate product delivery while preserving performance and reliability.

Key Features

• Robust theming
  • AppTheme wrapper with CSS variables, color schemes, tokens, and component-level overrides.
  • Consistent typography, palette, shape, and shadow system.
• Ready-to-use primitives
  • Cards, Buttons (CTA variants), Alerts, Tooltips, Loaders, Lists, Container/Hero sections, Headers, Avatars, Icons.
• Form system
  • FormProvider, schema composition, validations (length, alphabetic, numeric, required, email, password), localized field labels, aggregated error rendering.
• Dialog system
  • DialogProvider + useDialog hook for consistent modal/snackbar flows, dynamic actions, transitions, loading states.
• Accessibility and UX
  • Reduced motion-friendly transitions, focus visibility, contrast-aware color choices, and predictable hover/active states.
• TypeScript-first
  • Strong types for contexts, hooks, validations, and utilities.

Installation

# npm
npm install @worktif/purei

# yarn
yarn add @worktif/purei

Peer dependencies:

• react: ^19
• @mui/material: ^7.3
• @mui/icons-material
• @mui/styles (if using makeStyles-based parts)
• @emotion/react,
• @emotion/server
• @types/react,
• @types/react-dom

Usage

Minimal setup with theming and providers:

import React from 'react';
import ReactDOM from 'react-dom/client';

import { AppTheme } from '@worktif/purei';
import { DialogProvider, FormProvider } from '@worktif/purei';

function App() {
  return (
    <AppTheme>
      <DialogProvider>
        <FormProvider i18nSchema={{ email: 'Email', password: 'Password' }}>
          {/* Your application routes/components */}
        </FormProvider>
      </DialogProvider>
    </AppTheme>
  );
}

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

Cards, buttons, and loaders:

import React from 'react';

import { Box, Typography, Button } from '@mui/material';

import {
  GradientCard,
  CTAButtonSignUpColored,
  CustomLinearLoader,
  HighlightedDivider,
} from '@worktif/purei';

export function DashboardTile() {
  return (
    <GradientCard raised>
      <Typography variant="h5">Welcome back</Typography>
      <Typography variant="body2">Your services are healthy.</Typography>

      <Box sx={{ mt: 2 }}>
        <CustomLinearLoader variant="indeterminate" />
      </Box>

      <HighlightedDivider />

      <CTAButtonSignUpColored onClick={() => { /* navigate */ }}>
        Open Console
      </CTAButtonSignUpColored>
    </GradientCard>
  );
}

Dialog workflow with actions:

import React from 'react';

import { Button, Typography } from '@mui/material';

import { useDialog } from '@worktif/purei';

enum MyDialog {
  ConfirmDelete = 'confirm_delete',
}

export function DeleteButton() {
  const {
    openDialog,
    closeDialog,
    deliverDialogMessage,
    deliverDialogActions,
  } = useDialog<{ [MyDialog.ConfirmDelete]: boolean }>({
    [MyDialog.ConfirmDelete]: (
      <Typography>Are you sure you want to delete this resource?</Typography>
    ),
  });

  const onDelete = () => {
    // perform deletion
    closeDialog(MyDialog.ConfirmDelete);
  };

  const open = () => {
    deliverDialogActions(MyDialog.ConfirmDelete, [
      { children: 'Cancel', action: () => closeDialog(MyDialog.ConfirmDelete) },
      { children: 'Delete', variant: 'contained', action: onDelete },
    ]);
    openDialog(MyDialog.ConfirmDelete, 'Confirm Deletion');
  };

  return <Button color="error" onClick={open}>Delete</Button>;
}

Form composition and validation:

import React, { useContext, useEffect } from 'react';

import { TextField, Button } from '@mui/material';

import {
  FormsContext,
  FormBuilderSchema,
  FormFieldType,
  FormFieldValidationType,
  FormErrors,
} from '@worktif/purei';

const schema: FormBuilderSchema[] = [{
  form: [
    {
      type: FormFieldType.Text,
      name: 'email',
      value: '',
      validation: {
        [FormFieldValidationType.ShouldExist]: true,
        [FormFieldValidationType.Email]: true,
      },
    },
    {
      type: FormFieldType.Text,
      name: 'password',
      value: '',
      validation: { [FormFieldValidationType.Password]: 1 },
    },
  ],
}];

export function SignInForm() {
  const {
    composeSchema,
    setFieldValue,
    isError,
    getError,
    getFieldValue,
    setFormValue,
    hasError,
  } = useContext(FormsContext);

  useEffect(() => {
    composeSchema(schema, {});
  }, []);

  const submit = () => {
    setFormValue([{ email: getFieldValue('email'), password: getFieldValue('password') }], true, 0);
    if (!hasError(0)) {
      // proceed
    }
  };

  return (
    <>
      <TextField
        label="Email"
        value={getFieldValue('email') || ''}
        onChange={(e) => setFieldValue('email', e.target.value, 0)}
        error={isError('email', 0)}
        helperText={getError('email', 0)}
      />
      <TextField
        label="Password"
        type="password"
        value={getFieldValue('password') || ''}
        onChange={(e) => setFieldValue('password', e.target.value, 0)}
        error={isError('password', 0)}
        helperText={getError('password', 0)}
      />
      <Button onClick={submit} variant="contained">Sign In</Button>

      <FormErrors formValue={[{ email: getFieldValue('email'), password: getFieldValue('password') }]} formIndex={0} />
    </>
  );
}

API Reference

TypeScript-style signatures summarized. See Typedoc outputs for complete details.

Theming

• AppTheme(props)
  • children: ReactNode
  • disableCustomTheme?: boolean
  • defaultTheme?: ThemeOptions with CSS vars
  • themeComponents?: Components overrides

Dialog system

• DialogProvider: context provider
• useDialog<T>(messages?: DialogMessageInstance<T>): UseDialogValue<T>
  • openDialog(type, title?, notificationProps?, dialogMessageProps?, dialogActions?)
  • closeDialog(type?)
  • deliverDialogActions(type, actions)
  • deliverDialogMessage(type, messageSection)
  • actions, dialogMessage, dialogProps
• Notification(props: NotificationProps)
  • title?: string
  • closeTitle?: string
  • dialogComponent?: ReactElement
  • blurBackground?: boolean
  • closeColor?: string

Forms system

• FormProvider({ children, i18nSchema? })
• Form types
  • FormBuilderSchema
  • FormFieldType: 'text' | 'checkbox'
  • FormFieldValidationType: 'max-length' | 'min-length' | 'alphabetically' | 'should-exist' | 'email' | 'password' | 'numerical'
• Context functions
  • composeSchema(schema, body?)
  • setFormValue(value, isProcess?, index?)
  • setFieldValue(fieldName, value, index?)
  • getValue(fields?, index?)
  • getFieldValue(fieldName, index?)
  • getError(fieldName, index?)
  • isError(fieldName, index?)
  • hasError(index?)

UI primitives – find in repo src/ directory

• Buttons:
  • CTAButton,
  • CTAButtonSignUp,
  • CTAButtonSignUpColored,
  • CTAButtonAccount,
  • CTAButtonMenu,
  • GlowButton,
  • RippleButton,
  • BouncyButton,
  • BouncyOrderButton
• Cards:
  • GradientCard,
  • ThreeDCard,
  • LayeredShadowCard,
  • MotionCard,
  • InteractiveCard,
  • CardProduct,
  • LayeredCard
• Loaders:
  • CustomLinearLoader,
  • CustomLinearDialogLoader,
  • BrandProgressIndicator,
  • GradientProgress
• Layout:
  • BaseLayout,
  • SideNavLayout,
  • TopNavLayout,
  • WorkTifLayout
• Containers:
  • CustomContainer,
  • HeroContainer
• Alerts:
  • DynamicAlert,
  • AccessGrantedPanel
• Header/Nav:
  • GlassHeader,
  • SmartHeader,
  • HeaderContainer,
  • NavCore,
  • NavItem,
  • UserActions,
  • LoginButton,
  • LogoContainer,
  • LogoBlock
• Text:
  • GlowTitle,
  • Subtitle
• Tooltip:
  • CustomTooltip,
  • FadeTooltip
• Lists:
  • AnimatedListItem
• Images:
  • InteractiveAvatar,
  • GlowingAvatar,
  • RotatingIcon,
  • PulsingIcon,
  • NeonIcon
• Misc:
  • HighlightedDivider,
  • HighlightedDividerAlert,
  • ColorLine,
  • PlatformBadge

Utilities:

• date.localeDate(date?, options?, locale?): string
• encode.hashCode(str?): string
• fp.noop(): void
• react.EMPTY_ELEMENT
• react.utils.scrollTop(): void
• window.openUrl(url): void, window.copyUrl(url): void
• i18n.getFormFieldLabel(i18nSchema, fieldKey): string

Types:

• Maybe<T> = T | undefined
• Nullable<T> = T | null
• Other default informatics types

Use Cases

• Multi-product platforms standardization
  • Share consistent theming and component behavior across independent apps, ensuring consistent brand and accessibility.
• Fintech dashboards and consoles
  • Dialog + form contexts simplify confirmation flows, KYC steps, and transactional forms with validation and i18n seams.
• Cloud/SaaS admin interfaces
  • Unified presentation components (cards, alerts, tooltips, loaders) reduce implementation variance, improving UX reliability.
• High-security enterprise UX
  • Predictable focus styles, low-jank transitions, and compatible color contrasts improve accessibility and compliance.
• Design tokens rollout
  • AppTheme plugs in CSS vars + MUI color schemes to pilot and gradually adopt design tokens across large codebases.

Design Principles

• Composability: Small, focused primitives that compose into complex UIs.
• Predictability: Minimize "surprise" styles. Respect MUI patterns and theming contracts.
• Accessibility: Keyboard focus, contrast-aware palette choices, reduced motion-friendly transitions, semantic HTML via MUI.
• Performance:
  • Leverage MUI's CSS vars and style engine.
  • Avoid unnecessary re-renders via memoization in key contexts.
  • Keep animation costs low (transform/opacity).
• Stability: Strong TypeScript typing, defensive checks, and explicit contracts.
• Incremental adoption: Non-intrusive; can be layered on top of existing MUI apps.

Contributing

This section is intended for external publishers responsible for releasing the package to npm. Follow the sequence precisely to ensure auditability, semantic versioning integrity, and a clean release trail.

• Authenticate to the scoped registry
  • npm login --scope=@worktif
  • If you encounter a TLS/registry error, set the registry explicitly:
    • npm config set registry https://registry.npmjs.org/
• Complete your enhancement
  • Implement and locally validate your changes (types, build, docs as applicable).
• Open a Pull Request (PR)
  • Submit your changes for review.
  • Await approval before proceeding.
• Merge the PR
  • After approval, merge into main using your standard merge policy.
• Synchronize your local main
  • git checkout main
  • git pull to ensure you’re up to date.
• Prepare a release branch
  • Create a branch using the release template:
    • releases/v[your.semantic.version-[pre+[meta]]]-next-release-description
• Bump the version
  • Update the package version according to SemVer (major/minor/patch).
• Commit the version bump to the release branch
  • Commit only the version change (and any generated artifacts if required by your policy).
• Push the release branch
  • Push the branch to the remote to trigger any CI gates.
• Open a Release PR
  • Create a PR from the release branch to main.
  • Await approval and required checks.
• Merge the Release PR
  • Merge into main after approvals and passing checks.
• Final synchronization
  • Pull the latest changes from main locally.
• Validate the version in package.json
  • Ensure the version reflects the intended release.
• Publish
  • If the version was not increased (npm will reject):
    • Bump the version, commit, and then run yarn run publish:npm.
  • If the version has been increased and publishing fails unexpectedly:
    • Contact the maintainer at [email protected] with context (command output, Node/npm versions, CI logs).

Successful publish output resembles:

+ @worktif/purei@[your.semantic.version-[pre+[meta]]]
✨  Done in 28.81s.

Security/reporting: Use the repository issue tracker; for sensitive disclosures, contact the maintainer (below).

License

This project is licensed under the MIT.

• See LICENSE for the full license text.
• See NOTICE for attribution and relicensing details (re-licensed from BUSL-1.1 on 2025-09-16).
• See THIRD_PARTY_LICENSES.txt for third-party attributions and license texts.

Rationale: MIT promotes broad adoption while keeping the package compatible with enterprise distribution policies.

Maintainers / Contact

• Maintainer: Raman Marozau, [email protected]
• Organization: Work Target Insight Function

For enterprise support or integration guidance, reach out via email.