tessl/npm-payloadcms--ui

UI components library for Payload CMS providing React components, hooks, forms, and styling for building admin interfaces and extensible UI elements.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Utilities and Helpers

Name: tessl/npm-payloadcms--ui
Author: tessl

Utility functions for common tasks including form state building, URL handling, validation, data processing, and admin interface operations.

Form and Data Utilities

buildFormState

Construct form state from field schemas and data.

function buildFormState(options: {
  fieldSchema: FieldSchema[];
  data?: Record<string, unknown>;
  operation?: 'create' | 'update';
  locale?: string;
  id?: string | number;
}): FormState;

interface FormState {
  [path: string]: {
    value: unknown;
    valid: boolean;
    errorMessage?: string;
    disableFormData?: boolean;
    initialValue?: unknown;
  };
}

interface FieldSchema {
  name: string;
  type: string;
  required?: boolean;
  defaultValue?: unknown;
  validate?: (value: unknown, options: ValidateOptions) => string | true;
}

Usage example:

import { buildFormState } from '@payloadcms/ui/shared';

function createDocumentForm(fieldConfig, initialData) {
  const formState = buildFormState({
    fieldSchema: fieldConfig,
    data: initialData,
    operation: 'create',
    locale: 'en'
  });
  
  return formState;
}

buildTableState

Construct table state configuration from collection data.

function buildTableState(options: {
  columns: Column[];
  data: Record<string, unknown>[];
  sortColumn?: string;
  sortDirection?: 'asc' | 'desc';
}): TableState;

interface TableState {
  columns: Column[];
  data: Record<string, unknown>[];
  sort: {
    column?: string;
    direction: 'asc' | 'desc';
  };
}

parseSearchParams

Parse URL search parameters into a structured object.

function parseSearchParams(search: string): Record<string, unknown>;

Usage example:

import { parseSearchParams } from '@payloadcms/ui';

function handleUrlParams() {
  const params = parseSearchParams(window.location.search);
  // Returns: { page: "2", limit: "25", where: {...} }
  
  return params;
}

URL and Navigation Utilities

formatAdminURL

Format admin panel URLs with proper routing.

function formatAdminURL(args: {
  adminRoute: string;
  path: string;
  locale?: string;
}): string;

Usage example:

import { formatAdminURL } from '@payloadcms/ui';

function getCollectionURL(slug: string) {
  return formatAdminURL({
    adminRoute: '/admin',
    path: `/collections/${slug}`,
    locale: 'en'
  });
}

Navigation Handlers

Functions for handling common navigation actions.

function handleBackToDashboard(): void;
function handleGoBack(): void;
function handleTakeOver(args: {
  id: string | number;
  collectionSlug?: string;
  globalSlug?: string;
}): Promise<void>;

Navigation Item Utilities

function groupNavItems(items: NavItem[]): GroupedNavItems;

interface NavItem {
  label: string;
  url: string;
  group?: string;
  active?: boolean;
}

interface GroupedNavItems {
  [group: string]: NavItem[];
}

Validation and Permissions

hasSavePermission

Check if user has permission to save a document.

function hasSavePermission(args: {
  collectionSlug?: string;
  globalSlug?: string;
  operation: 'create' | 'update';
  permissions?: SanitizedPermissions;
}): boolean;

Permission Checking

function isEditing(operation: string): boolean;
function isClientUserObject(user: unknown): user is ClientUser;

Data Processing

sanitizeID

Sanitize document ID for safe usage.

function sanitizeID(id: unknown): string;

Field Processing Utilities

function reduceToSerializableFields(args: {
  fields: FieldConfig[];
  data: Record<string, unknown>;
}): Record<string, unknown>;

function filterFields(args: {
  fields: FieldConfig[];
  operation: 'create' | 'update' | 'read';
  permissions?: Record<string, unknown>;
}): FieldConfig[];

function mergeFieldStyles(
  baseStyles: Record<string, unknown>,
  customStyles?: Record<string, unknown>
): Record<string, unknown>;

Date and Formatting

formatDate

Format dates for display in admin interface.

function formatDate(args: {
  date: Date | string;
  pattern?: string;
  locale?: string;
}): string;

Usage example:

import { formatDate } from '@payloadcms/ui';

function DisplayDate({ date }) {
  const formatted = formatDate({
    date: date,
    pattern: 'PPP',
    locale: 'en-US'
  });
  
  return <span>{formatted}</span>;
}

Document Title Formatting

function formatDocTitle(args: {
  data: Record<string, unknown>;
  useAsTitle?: string;
  fallback?: string;
}): string;

function formatTimeToNow(date: Date | string): string;

Locale Utilities

function findLocaleFromCode(
  code: string,
  locales: LocaleConfig[]
): LocaleConfig | undefined;

interface LocaleConfig {
  label: string;
  code: string;
}

Table and Column Utilities

getInitialColumns

Initialize table columns from configuration.

function getInitialColumns(args: {
  collectionConfig: CollectionConfig;
  preferences?: ColumnPreferences;
  defaultColumns?: string[];
}): Column[];

interface ColumnPreferences {
  [field: string]: {
    active: boolean;
    width?: number;
  };
}

Server-Side Utilities (RSC)

Utilities available in the RSC (React Server Components) export for server-side rendering.

getFolderResultsComponentAndData

Fetch folder data and component for server-side rendering.

function getFolderResultsComponentAndData(args: {
  collectionSlug: string;
  folder?: string;
  locale?: string;
  where?: Record<string, unknown>;
  limit?: number;
  page?: number;
}): Promise<{
  Component: React.ComponentType;
  data: FolderResult;
}>;

interface FolderResult {
  docs: Record<string, unknown>[];
  folders: FolderConfig[];
  totalDocs: number;
}

renderFilters

Server-side filter rendering utility.

function renderFilters(args: {
  collectionConfig: CollectionConfig;
  where?: Record<string, unknown>;
  locale?: string;
}): React.ReactNode;

renderTable

Server-side table rendering utility.

function renderTable(args: {
  data: Record<string, unknown>[];
  columns: Column[];
  collectionSlug: string;
}): React.ReactNode;

copyDataFromLocaleHandler

Handle copying data between locales.

function copyDataFromLocaleHandler(args: {
  data: Record<string, unknown>;
  fromLocale: string;
  toLocale: string;
  fields: FieldConfig[];
}): Record<string, unknown>;

Request and API Utilities

HTTP Request Utilities

const requests: {
  get: (url: string, options?: RequestOptions) => Promise<Response>;
  post: (url: string, options?: RequestOptions) => Promise<Response>;
  patch: (url: string, options?: RequestOptions) => Promise<Response>;
  delete: (url: string, options?: RequestOptions) => Promise<Response>;
};

interface RequestOptions {
  headers?: Record<string, string>;
  body?: BodyInit;
  signal?: AbortSignal;
}

Utility Usage Examples

Form State Management

import { buildFormState, useForm } from '@payloadcms/ui';

function DynamicForm({ fieldConfig, initialData }) {
  const formState = buildFormState({
    fieldSchema: fieldConfig,
    data: initialData,
    operation: 'update'
  });

  const { submit, validate } = useForm();

  const handleSubmit = async () => {
    if (validate()) {
      await submit();
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Form fields */}
    </form>
  );
}

Permission-Based Rendering

import { hasSavePermission, useAuth } from '@payloadcms/ui';

function DocumentActions({ collectionSlug }) {
  const { permissions } = useAuth();
  
  const canSave = hasSavePermission({
    collectionSlug,
    operation: 'update',
    permissions
  });

  return (
    <div>
      {canSave && (
        <Button type="submit">Save</Button>
      )}
    </div>
  );
}

URL Management

import { formatAdminURL, parseSearchParams } from '@payloadcms/ui';

function NavigationHelper() {
  const currentParams = parseSearchParams(window.location.search);
  
  const getEditURL = (id: string) => {
    return formatAdminURL({
      adminRoute: '/admin',
      path: `/collections/posts/${id}`
    });
  };

  return {
    currentParams,
    getEditURL
  };
}

Date Display

import { formatDate, formatTimeToNow } from '@payloadcms/ui';

function DateDisplay({ createdAt, updatedAt }) {
  return (
    <div>
      <span>Created: {formatDate({ date: createdAt, pattern: 'PPP' })}</span>
      <span>Updated: {formatTimeToNow(updatedAt)}</span>
    </div>
  );
}

Types

interface ValidateOptions {
  data: Record<string, unknown>;
  siblingData: Record<string, unknown>;
  operation: 'create' | 'update';
  id?: string | number;
}

interface Column {
  accessor: string;
  label: string;
  active?: boolean;
  width?: number;
}

interface CollectionConfig {
  slug: string;
  fields: FieldConfig[];
  admin?: AdminConfig;
}

interface FieldConfig {
  name: string;
  type: string;
  label?: string;
  required?: boolean;
  admin?: Record<string, unknown>;
}

interface SanitizedPermissions {
  collections: Record<string, CollectionPermission>;
  globals: Record<string, GlobalPermission>;
  canAccessAdmin: boolean;
}

interface CollectionPermission {
  create: boolean;
  read: boolean;
  update: boolean;
  delete: boolean;
}

interface GlobalPermission {
  read: boolean;
  update: boolean;
}

interface ClientUser {
  id: string;
  email?: string;
  [key: string]: unknown;
}

interface FolderConfig {
  id: string;
  name: string;
  parent?: string;
}

Install with Tessl CLI