KatebTech Core

Shared core utilities, primitive UI components, route builders, and foundational patterns for Kateb Tech projects.

Purpose

@katebtech/core contains reusable low-level building blocks used across Kateb Tech websites and apps.

It should stay focused on primitives, generic helpers, shared public types, and foundational patterns. Website-specific business logic, layouts, page sections, app data, SEO, and feature workflows belong in the consuming app or in a higher-level package.

Package Overview

This package provides:

• primitive UI components such as Button, Header, P, List, and form controls
• server action helpers for parsing FormData, converting checkbox values, and returning validation errors
• form security helpers for bot-trap checks, request validation, client IP lookup, and Cloudflare Turnstile verification
• shared route builders for auth, admin, blog, public, API, and public resource paths
• shared content assets and language statements
• date, database, SVG, URL, class name, RTL text, environment, and slug helpers

File Structure

src
├── button
├── content
├── date
├── db
├── form
│   ├── actions
│   ├── controls
│   ├── fields
│   └── security
├── routes
├── svg
├── typography
├── utils
└── index.ts

Import Style

Prefer specific package subpaths when consuming package APIs:

import { Button } from "@katebtech/core/button";
import { KATEB_TECH_LOGO } from "@katebtech/core/content";
import { formatDateTimeAU } from "@katebtech/core/date";
import { createSqlClient } from "@katebtech/core/db";
import { parseActionFormData } from "@katebtech/core/form/actions";
import { Input } from "@katebtech/core/form/controls";
import { CONTACT_FIELDS } from "@katebtech/core/form/fields";
import { checkFormBotTrap } from "@katebtech/core/form/security";
import { adminRoutes } from "@katebtech/core/routes";
import { svgToDataUrl } from "@katebtech/core/svg";
import { Header } from "@katebtech/core/typography";
import { cn } from "@katebtech/core/utils";

The root import is available for broad convenience, but package-level code should usually import from the narrow subpath that owns the API.

Inside this package, use relative imports:

import { FieldError } from "./FieldError";

Avoid importing the package from itself:

import { FieldError } from "@katebtech/core/form/controls";

Package Rules

Keep @katebtech/core small, reusable, and predictable.

• Export public components, helpers, and useful public types from each module index.ts.
• Keep internal implementation types private.
• Use PascalCase for React components.
• Use camelCase for functions and variables.
• Use UPPER_SNAKE_CASE for shared constants.
• Use descriptive file and folder names.
• Avoid any unless the API requires it.
• Prefer explicit public types, readonly data, discriminated unions for result shapes, and as const for useful literal types.
• Use relative imports inside the package.
• Avoid circular dependencies.
• Do not depend on higher-level packages such as @katebtech/layout or app packages.

Dependency direction:

@katebtech/core
    ↓
@katebtech/layout
    ↓
@katebtech/pages or app packages

Module Documentation

Button

Exports:

• Button
• ButtonProps
• ButtonVariant
• ButtonSize

Import:

import { Button } from "@katebtech/core/button";

Use Button for shared button styling across button and Next.js link usage.

Content

Exports:

• KATEB_TECH_LOGO
• List
• ENGLISH_LANGUAGE_STATEMENT
• OTHER_LANGUAGES_STATEMENT
• EnglishLanguageKey
• EgnlishLanguageKey deprecated alias
• OtherLanguageKey
• OtherLanguage
• ListProps

Import:

import { KATEB_TECH_LOGO, List } from "@katebtech/core/content";

Use content exports for shared brand assets, reusable content lists, and shared language statements.

Date

Exports:

• formatDateTimeAU
• toLocalDateTimeInput

Import:

import { formatDateTimeAU, toLocalDateTimeInput } from "@katebtech/core/date";

Use date helpers for shared Australian date-time formatting and date input conversion.

Database

Exports:

• createSqlClient
• SqlFragment

Import:

import { createSqlClient, type SqlFragment } from "@katebtech/core/db";

Use createSqlClient to create a PostgreSQL client with shared defaults. Application-specific tables, migrations, queries, and repository functions should stay inside the app that owns the data.

Form Actions

Exports:

• parseActionFormData
• parseFormData
• formDataToObject
• toActionErrors
• toActionErrors2
• toBoolean
• ActionState
• FieldErrors
• BooleanKeys
• CamelizeKeys
• ParseActionFormDataOptions
• ParseActionFormDataResult
• ParseFormDataOptions
• FormDataToObjectOptions

Import:

import { parseActionFormData, toBoolean } from "@katebtech/core/form/actions";
import type { ActionState } from "@katebtech/core/form/actions";

Basic usage:

import { parseActionFormData } from "@katebtech/core/form/actions";
import { z } from "zod";

const schema = z.object({
  email: z.email("Enter a valid email address."),
  subscribe: z.boolean(),
});

export const submitForm = async (
  _previousState: unknown,
  formData: FormData,
) => {
  const result = parseActionFormData({
    formData,
    schema,
    booleanFields: ["subscribe"],
  });

  if (!result.ok) {
    return result.state;
  }

  return {
    ok: true,
    message: "Submitted successfully.",
  };
};

Use these helpers inside server actions to keep form parsing, validation, and error shapes consistent.

Form Controls

Exports:

• Checkbox
• FieldError
• FormErrorsMessage
• Input
• Select
• Textarea
• CheckboxProps
• FieldErrorProps
• FormErrorsMessageProps
• InputProps
• SelectOption
• SelectProps
• TextareaProps

Import:

import {
  Checkbox,
  Input,
  Select,
  Textarea,
} from "@katebtech/core/form/controls";

Basic usage:

<Input id="email" label="Email" type="email" required />

<Select
  id="service"
  label="Service"
  options={[
    { value: "web-design", label: "Web Design" },
    { value: "seo", label: "SEO" },
  ]}
/>

Use these components for reusable form UI. Select is a native select component; it submits the selected value and accepts a standard select onChange handler.

Form Fields

Exports:

• CONTACT_FIELDS

Import:

import { CONTACT_FIELDS } from "@katebtech/core/form/fields";

Use field constants to keep UI controls, validation schemas, and server actions aligned.

Form Security

Exports:

• FormBotTrapFields
• TurnstileWidget
• TURNSTILE
• checkAllowedFormRequest
• checkFormBotTrap
• getClientIp
• verifyTurnstileToken
• FormBotTrapFieldsProps
• TurnstileAction
• TurnstileWidgetProps

Import:

import {
  FormBotTrapFields,
  TurnstileWidget,
  checkAllowedFormRequest,
  checkFormBotTrap,
  getClientIp,
  verifyTurnstileToken,
} from "@katebtech/core/form/security";

Basic usage:

<form action={formAction} noValidate>
  <FormBotTrapFields />
  <TurnstileWidget siteKey={siteKey} action="contact-enquiry" />
  <button type="submit">Submit</button>
</form>

Application code remains responsible for allowed domains, Turnstile keys, validation, rate limiting, logging, email delivery, and application-specific database operations.

Routes

Exports:

• adminRoutes
• apiRoutes
• authRoutes
• blogRoutes
• publicResources
• publicRoutes
• route constants

Import:

import { adminRoutes, authRoutes, blogRoutes } from "@katebtech/core/routes";

Use route helpers instead of scattering hard-coded shared route strings through components, actions, redirects, navigation, or metadata.

SVG

Exports:

• escapeSvgText
• katebTechnologyIllustration
• svgToDataUrl

Import:

import { katebTechnologyIllustration, svgToDataUrl } from "@katebtech/core/svg";

Use SVG helpers for package-owned SVG rendering and data URL generation.

Typography

Exports:

• Header
• P
• AsTag
• HeaderProps
• HeadingAlign
• HeadingSize
• ParaSize
• PProps

Import:

import { Header, P } from "@katebtech/core/typography";

Use typography components for shared heading and paragraph styling. Use as on Header for semantic heading structure.

Utils

Exports:

• cn
• requiredEnv
• isRTLText
• slugify
• unSlugify
• URL helpers from src/utils/url.ts

Import:

import { cn, getBaseUrl, requiredEnv, slugify } from "@katebtech/core/utils";

Use utilities for class merging, environment checks, URL creation, RTL detection, and slug conversion.