antd-toolkit

name: antd-toolkit description: > antd-toolkit (j7-dev/antd-toolkit) v1.3.x — React component library wrapping antd v5 with Refine integration helpers, WordPress / WooCommerce specific UI, BlockNote-based rich-text editor, and a Bunny Stream media library. Use this skill whenever code imports from 'antd-toolkit', 'antd-toolkit/wp', or 'antd-toolkit/refine', or when package.json contains "antd-toolkit". Triggers include LocaleProvider, EnvProvider, ActionButton, ObjectTable, SimpleModal, SimpleDrawer, BlockNote, MediaLibrary, BunnyProvider, dataProvider, bunnyStreamDataProvider, useWoocommerce, ProductFilter, UserAvatarUpload, notificationProvider, useColumnSearch, and the WP / WooCommerce constant sets (POST_STATUS, ORDER_STATUS, PRODUCT_TYPES). Do NOT search the web for antd-toolkit docs — use this skill instead.

antd-toolkit API Reference

antd-toolkit (npm package antd-toolkit, repo j7-dev/antd-toolkit) is a React component library that bundles three things: (1) opinionated wrappers around antd v5, (2) Refine integration helpers, (3) WordPress / WooCommerce admin building blocks. It also ships a BlockNote-based rich text editor and a Bunny Stream media library.

Version coverage: antd-toolkit@1.3.x (tested against 1.3.223). Built on antd ^5.25, React 18.3, @refinedev/core ^4.58, @refinedev/antd ^5.47, @blocknote ^0.49, @tanstack/react-query ^5.100, jotai ^2.12, dayjs ^1.11.

Three Entry Points

The package ships three independent ESM entries — each must be imported from its own subpath:

// Core
import { LocaleProvider, useLocale, ActionButton, cn, defaultImage } from 'antd-toolkit'
import type { TLocale, TLimit } from 'antd-toolkit'

// WordPress / WooCommerce
import { useWoocommerce, ProductName, UserFilter, stringToBool } from 'antd-toolkit/wp'
import type { TProductBaseRecord, TUserBaseRecord, TWoocommerce } from 'antd-toolkit/wp'

// Refine integration
import { dataProvider, notificationProvider, BunnyProvider, useBunny } from 'antd-toolkit/refine'

// Stylesheet (only required for the core entry; auto-loaded once via side-effect)
import 'antd-toolkit/style.css'

The dist/style.css is automatically loaded when you import the JS entry (the package marks **/*.css as a sideEffect). Importing it explicitly is only needed if your bundler tree-shakes side-effects.

Reference Files

Read only what your task needs. Each file contains complete API signatures, all props with TypeScript types, defaults, and runnable patterns.

Mandatory Setup: LocaleProvider

Most components use useLocale(namespace) internally for i18n. Wrap your tree once at the top — without it the components fall back to the default zh_TW (繁體中文) locale.

import { LocaleProvider, en_US } from 'antd-toolkit'

function App() {
  return (
    <LocaleProvider locale={en_US}>
      <YourApp />
    </LocaleProvider>
  )
}

Built-in locales: zh_TW (default), en_US, ja_JP. To customise, spread one of the built-ins and override only the namespaces you need (see references/main-hooks-utils.md § Locales).

Important: antd-toolkit's LocaleProvider only translates antd-toolkit components. Antd's own UI text (Pagination, Empty, etc.) requires antd's ConfigProvider + locale separately.

Common Setup with Refine

Most batch-CRUD and Bunny components assume Refine is configured with the bundled dataProvider. Typical bootstrap:

import { Refine } from '@refinedev/core'
import { useNotificationProvider } from '@refinedev/antd'
import { dataProvider, notificationProvider, BunnyProvider } from 'antd-toolkit/refine'
import { LocaleProvider, EnvProvider } from 'antd-toolkit'
import axios from 'axios'

const axiosInstance = axios.create({ headers: { 'X-WP-Nonce': window.appData.nonce } })

<LocaleProvider>
  <EnvProvider env={{
    SITE_URL: 'https://example.com',
    AJAX_URL: '...', API_URL: '...', NONCE: '...',
    CURRENT_USER_ID: 1, CURRENT_POST_ID: false, PERMALINK: '',
    APP_NAME: 'my-app', KEBAB: 'my-app', SNAKE: 'my_app',
  }}>
    <BunnyProvider
      bunny_library_id="123"
      bunny_stream_api_key="xxx"
      bunny_cdn_hostname="vz-xxx.b-cdn.net">
      <Refine
        dataProvider={{
          default: dataProvider('https://api.example.com', axiosInstance),
        }}
        notificationProvider={notificationProvider}>
        {/* your routes */}
      </Refine>
    </BunnyProvider>
  </EnvProvider>
</LocaleProvider>

Tailwind Class Prefix

All internal CSS classes are prefixed with at- (configured via tailwind prefix: 'at-'). When using the bundled stylesheet, at-flex, at-mb-4, etc. are scoped to antd-toolkit and won't collide with your project's Tailwind. The cn() util re-exported from the package is twMerge(clsx(args)) and merges normally — you can mix prefixed and unprefixed classes in your own components.

Behavioural Conventions

These show up everywhere; understanding them once removes most guesswork.

Boolean as 'yes' | 'no' strings

WordPress meta values commonly serialise booleans as 'yes' / 'no'. The Switch, Segmented and many filter components in formItem/* and wp/* round-trip through stringToBool / boolToString. When wiring forms to a WP REST endpoint use those helpers — do not assume a JS boolean.

import { stringToBool, boolToString } from 'antd-toolkit/wp'
stringToBool('yes')   // true (also: '1', 1, 'true', 'on', true)
boolToString(true)    // 'yes'

Date as Unix timestamp

The bundled DatePicker and RangePicker (under formItem/*) automatically convert between Dayjs (UI) and Unix seconds (storage). When the form value comes from REST as a number, the component handles parsing — see references/main-form-items.md § DatePicker. Manual conversion utilities: parseDatePickerValue, formatDatePickerValue, parseRangePickerValue, formatRangePickerValue.

useLocale namespace pattern

Each component reads its own namespace, e.g. useLocale('ActionButton') returns just the ActionButton slice of TLocale. To override texts, spread zh_TW and replace just the slice you need. Adding a new component? It must declare its key in TLocale (in lib/main/locales/types.ts) and provide values in all three locales.

Variant pattern for icon vs text vs both

Several components (ActionButton, PopconfirmDelete, BooleanSegmented, ProductStock) accept a type prop with values like 'icon' | 'text' | 'both' or 'icon' | 'button' to switch presentation. The default is usually 'both' or 'icon' — check the component's signature in the relevant reference file.

Two modal/drawer flavours

SimpleModal and SimpleDrawer are not ant-design's Modal/Drawer. They're lighter, render via Portal, animate with CSS, and pair with useSimpleModal() / useSimpleDrawer() hooks that return { show, close, modalProps } (or drawerProps). Use them for toolkit-managed UI (e.g. media library); use antd's own Modal/Drawer elsewhere.

Quick Cheat-Sheet — When To Use What

Things to NOT do

• Never re-export from antd-toolkit/wp to use core symbols. The wp entry imports from core; reaching into wp for cn() or LocaleProvider works at runtime but bloats the bundle. Always use the most specific entry.
• Don't construct dataProvider outside of a Refine <Refine dataProvider={…}>. Most batch components call useApiUrl() from @refinedev/core, which throws without a Refine provider in scope.
• Don't pass a JS boolean to the toolkit Switch / Segmented. They normalise to 'yes' | 'no'. Pre-store as string. (Use the antd Switch directly if you want a JS boolean.)
• Don't omit <EnvProvider> if you call useEnv(), BackToWpAdmin, DescriptionDrawer, or any media library component. Those expect SITE_URL, NONCE, API_URL, etc. (see references/main-hooks-utils.md § EnvProvider).
• Don't use the bundled Card wrapper if you want antd's Card.Meta etc. It's <AntdCard> for showCard=true, otherwise pass-through children — Meta is unaffected but bear in mind the wrapper has no other surface.
• Don't expect Bunny's dataProvider to support createMany/updateMany/deleteMany. It only ships getList / getMany / getOne / create / update / deleteOne / custom.

Useful Type Aliases

import type {
  // Core
  TLocale, TConstant, TGetColumnFilterProps, TLimit, TLimitType, TLimitUnit,
  TVideo, TVideoType, THttpMethods, THttpMethodsWithBody, TOrder, TOrderBy,
  TEnv, TExpireDate,
} from 'antd-toolkit'

import type {
  // WordPress / WooCommerce
  TImage, TTerm, TPostStatus, TOrderStatus,
  TUserBaseRecord, TProductBaseRecord, TProductVariationBase, TProductAttribute,
  TProductType, TProductStockStatus, TBackorders,
  TWoocommerce, TTaxonomy, TAttachment,
} from 'antd-toolkit/wp'

import type {
  // Refine module
  TGrantedItemBase, TProductFilterProps, UseCustomMutationParams,
  TBunnyVideo, TGetVideosResponse, TUploadVideoResponse, TUploadStatus, TFileInQueue,
  TMediaLibraryProps, TFileStatus,
} from 'antd-toolkit/refine'

(The TMediaLibraryProps type exists separately in both wp and refine namespaces — they look similar but the WP one accepts (TAttachment | TImage)[] while the Bunny one accepts TBunnyVideo[]. Pick the right entry.)