Arkyn v2.2.3 → v3.0.2 Migration Guide

High-level summary

• Framework decoupling. Every @remix-run/* peer dependency is dropped across components and server. Hooks/utilities that used to read Remix's useActionData/useFetchers/useLocation/useNavigate directly (useFieldErrors, useAutomation, useScopedParams, Pagination) now take plain data/strings as arguments and leave routing/data-fetching to the consumer.
• @arkyn/types is gone. All prop/context types (previously imported from the standalone @arkyn/types package) are now declared inline in each component/hook/provider file and are largely not re-exported by name. See Removed: @arkyn/types.
• ESM-only, unbundled, tree-shakeable output. Every package drops its single dist/bundle.js in favor of unbundled per-module ESM output plus a granular exports map (subpath imports like @arkyn/components/button, @arkyn/shared/formatToCep, etc.). See Tooling / packaging changes.
• New form-field architecture. The Remix-coupled Form/FormController/FormLabel/FormError components and useFieldErrors() hook are replaced by a generic FormProvider + useForm() + FieldWrapper/FieldLabel/FieldError trio, used consistently across Input, Select, MultiSelect, Textarea, RadioGroup, RichText, and the upload components.
• @arkyn/newcomponents (an experimental v2.1.0 package) is folded into @arkyn/components. Its Badge/Button implementation (not the old @arkyn/components one) is what shipped in v3.
• Google Maps → Mapbox. GoogleMap is replaced by MapView, built on mapbox-gl instead of @react-google-maps/api, with a different props/marker shape and a Mapbox access token instead of a Google Maps API key.
• Several components removed with no replacement: Breadcrumb, Card, Skeleton.
• Several components are new: AudioPlayer, Calendar, FullCalendar, CardTabButton/CardTabContainer, CurrencyInput, MaskedInput, FieldError/FieldLabel/FieldWrapper, GoogleAnalytics.
• @arkyn/server gains an HTTP client (ApiService), logging services, and absorbs all validators from @arkyn/shared, plus a new validateEmail. Zod moves from a bundled v3 dependency to a peer dependency on Zod v4 — a breaking major-version bump for any schema/validator code.
• @arkyn/shared drops the uuid dependency (native crypto.randomUUID), and several date/format functions changed default enum literals and rounding/timezone behavior.
• @arkyn/templates's countries data dropped the prefix field from every entry and Brazil's mask changed from a single string to a two-entry array — the first breaking change to a widely-consumed data shape.

Package inventory changes

• @arkyn/components (2.2.3) → @arkyn/components (3.0.1-beta.207) — continued
• @arkyn/newcomponents (2.1.0, experimental) → removed — merged into @arkyn/components
• @arkyn/server (2.2.3) → @arkyn/server (3.0.1-beta.207) — continued
• @arkyn/shared (2.2.3) → @arkyn/shared (3.0.1-beta.207) — continued
• @arkyn/templates (2.2.3) → @arkyn/templates (3.0.1-beta.207) — continued
• @arkyn/types (2.2.3) → removed — no replacement package; types co-located per-file
• (new) → apps/development (new, private: true, internal playground app — not published)

@arkyn/components

Package metadata & build

• main
  • v2.2.3: ./dist/bundle.js
  • v3.0.2: ./dist/index.js
• module
  • v2.2.3: (none)
  • v3.0.2: ./dist/index.js
• exports map
  • v2.2.3: (none — root import only)
  • v3.0.2: ~122 subpath entries: one JS+.d.ts pair per component/hook/provider/service, plus a <name>.css sibling for every component with styles, plus "./styles" for the full aggregate stylesheet
• peerDependencies
  • v2.2.3: @remix-run/react ^2.15.0, react ^18.3.1, react-dom ^18.3.1
  • v3.0.2: react >=18.0.0, react-dom >=18.0.0, plus many new, mostly-optional peers: @react-google-maps/api, @react-input/mask, html-react-parser, is-hotkey, lucide-react, mapbox-gl, react-hot-toast, react-scroll, slate, slate-history, slate-react
• dependencies
  • v2.2.3: bundled all of the above libraries directly
  • v3.0.2: only internal workspace deps: @arkyn/shared, @arkyn/templates
• files
  • v2.2.3: controlled by root .npmignore
  • v3.0.2: explicit allowlist: ["dist", "README.md", "LICENSE.txt", "styles.d.ts"]

import "@arkyn/components/styles";           // all components' CSS

import { Button } from "@arkyn/components/button";
import "@arkyn/components/button.css";       // just Button's CSS (+ anything it renders internally)

Barrel export changes (src/index.ts)

• Import paths moved from PascalCase folders (./components/Alert) to camelCase (./components/alert), and most components lost their local barrel index.ts — every subcomponent is exported directly from the package root.
• Renamed: GoogleProvider → PlacesProvider; useFieldErrors → useForm (behavior changed, see Providers); getHtmlFromRichTextValue → toHtml; getRichTextValueFromHtml → toRichTextValue.
• Removed: Card, Skeleton, Breadcrumb family (BreadcrumbContainer, BreadcrumbLink), Form family (FormController, FormLabel, FormError, useFormController), Toast (the standalone visual component — was already dead code, see Toast), GoogleMap, GoogleSearchPlaces, isHtml, morpheme, GenerateIcon, generatePagesArray, formatCurrency, clearNumber, maskValues, normalizeValue (internal service helpers no longer exported).
• New: AudioPlayer, Calendar, FullCalendar, CardTabButton, CardTabContainer, CurrencyInput, MaskedInput, FieldError, FieldLabel, FieldWrapper, FormProvider, GoogleAnalytics, MapView, SearchPlaces, useForm, useScrollLock, useSearchAutomation, useSlider.

Removed components (no replacement)

• Breadcrumb (BreadcrumbContainer, BreadcrumbLink) — Fully removed. No equivalent anywhere in v3.0.2.
• Card — Plain <div> wrapper, fully removed. The new CardTabButton/CardTabContainer are an unrelated tabbed-selector UI, not a generic container replacement — use a plain <div> instead.
• Skeleton — Shimmer-loading placeholder, fully removed with no equivalent.
• CpfCnpjInput (internal Input type="cpf-cnpj" variant) — Removed as a ready-made component. CPF/CNPJ formatting logic moved to @arkyn/shared (formatToCpf, formatToCnpj); consumers must now compose MaskedInput + these formatters manually.

Renamed / restructured components (same concept, breaking prop changes)

Alert (alertContainer, alertContent, alertDescription, alertIcon, alertTitle)

• AlertContainer: prop schema renamed to scheme (breaking).
• Logic unchanged otherwise.

AudioUpload

• onUpload renamed to onChange.
• Label/error rendering now uses shared FieldWrapper/FieldLabel/FieldError instead of local subcomponents; error source is now useForm() instead of the Remix-coupled useFieldErrors().
• Playback UI extracted into a new standalone AudioPlayer component (src, disabled, onPlayAudio, onPauseAudio receiving { currentTime, totalTime, formattedCurrentTime, formattedTotalTime }).

Badge

• Now the @arkyn/newcomponents implementation (see Removed: @arkyn/newcomponents), not the old @arkyn/components one.
• scheme union gains "secondary".
• Default size changed from "md" to "lg" — breaking if you relied on the implicit default.
• Children now wrapped in a <p> internally (was raw children).

Button

• Now the @arkyn/newcomponents implementation.
• scheme union gains "secondary". No other prop changes.

Divider

• No changes — continued as-is (path/casing only).

Drawer (drawer, drawerHeader, drawerContext.tsx)

• DrawerContainer: prop isVisibled renamed to isVisible (typo fix, breaking).
• Animation swapped from framer-motion to plain CSS + onAnimationEnd (framer-motion dependency dropped for this component).
• New internal useScrollLock(isVisible) locks body scroll while open.
• Public useDrawer/DrawerProvider (multi-drawer registry) API is unchanged — same drawerIsOpen(key)/drawerData(key)/openDrawer(key, data?)/closeDrawer(key), just re-sourced from providers/drawerProvider.tsx. Note there's also a second, unrelated internal useDrawer exported from drawer/drawerContext.tsx (only used by DrawerHeader's close button) — don't confuse the two.

FacebookPixel

• No prop changes. FacebookPixelProps is now exported by name (one of the few components that still does this).

FileUpload

• onUpload renamed to onChange. Same FieldWrapper/FieldLabel/FieldError + useForm() rework as AudioUpload.

Form → removed; replaced by FieldWrapper + FieldLabel + FieldError + FormProvider + useForm()

• Old: FormController auto-derived field name/id from a nested input ref and exposed { error, id, inputRef } via context; FormLabel/FormError read that context implicitly. Errors came from useFieldErrors(), which read Remix's useActionData()/useFetchers()/useNavigation() directly.
• New: FormProvider({ children, fieldErrors?, form? }) holds fieldErrors explicitly passed in by the app (e.g. from useActionData() in a Remix app, or any other source). useForm() returns { fieldErrors }. FieldWrapper (orientation?), FieldLabel (showAsterisk?, requires explicit htmlFor), and FieldError (renders children or null) are plain, context-free primitives that every form-field component (Input, Select, MultiSelect, Textarea, RadioGroup, upload components, RichText) now composes itself.
• Migration action: wrap forms in <FormProvider fieldErrors={actionData?.fieldErrors}>, remove any FormController/FormLabel/FormError usage, and stop relying on automatic Remix wiring.

GoogleMap → MapView (breaking third-party SDK swap)

• Rebuilt on Mapbox GL (mapbox-gl) instead of @react-google-maps/api.
• coordinates?: {lat,lng} → coordinates?: Coordinate | Coordinate[] (Coordinate = {lat, lng, data?, popUp?}) — now supports multiple markers with attached data and custom popups.
• New required accessToken: string (Mapbox public token) replaces GoogleProvider/googleMapsApiKey.
• New onMarkerClick?: (coordinate) => void.
• draggable prop removed — markers are no longer draggable.
• Flag this as the highest-risk change in the release: different SDK, different API key type, different marker/coordinate shape.

GoogleSearchPlaces → SearchPlaces

• Still built on @react-google-maps/api's StandaloneSearchBox (not swapped to Mapbox).
• onPlaceChanged payload field renames: district → neighborhood, cep → postalCode.
• More resilient place-type matching (checks multiple Google Places type keys instead of one).
• Provider GoogleProvider → PlacesProvider: prop googleMapsApiKey → apiKey; children pattern changed to a render prop — children: (isLoaded: boolean) => ReactNode instead of plain ReactNode. Update every <GoogleProvider>{children}</GoogleProvider> call site.

GoogleTagManager

• Unchanged. A new, independent GoogleAnalytics component was added alongside it (GA4 support: measurementId, showInDevMode?) — not a rename or replacement of GTM.

IconButton

• scheme union gains "secondary". No other changes.

ImageUpload

• onUpload renamed to onChange, now (url: string) => void (no longer optional).
• Gains className, unShowFieldTemplate, orientation props not present on AudioUpload/FileUpload (inconsistent prop parity across the three upload components — flagged for maintainers, not just consumers). Note the orientation JSDoc says default "horizontal" but the code defaults to "vertical" — verify actual behavior before relying on the default.

Input / CurrencyInput / MaskedInput / PhoneInput

• Input: narrowed to plain text input only (no more type variant dispatch). sufix renamed to suffix. Adds label, errorMessage, showAsterisk, orientation, unShowFieldTemplate. New disabled-state behavior: shows the current value as placeholder text when disabled.
• CurrencyInput (new standalone): locale is now a required, fixed union of 22 currency codes (was a free-form locale+currency string pair). value/defaultValue changed from string to number. onChangeValue renamed to onChange. onKeyPress callback removed.
• MaskedInput (new standalone): replacement is now required (was optional). No type prop. Does not use the shared FieldTemplate pattern — composes FieldWrapper/FieldLabel/FieldError manually and has no orientation prop, unlike the other three (inconsistency to flag).
• PhoneInput: folder/subcomponents lowercased. Adds label, errorMessage, showAsterisk, orientation, unShowFieldTemplate, and a new optional value prop (component can now be controlled, was uncontrolled-only). defaultCountry renamed to defaultCountryIso. Internal country/mask parsing now delegates to @arkyn/shared's findCountryMask/formatToPhone instead of local utilities; CountryType.mask is now string | string[]. Gains smart dropdown positioning and useScrollLock.
• CpfCnpjInput: removed (see Removed components).

Modal (modalContainer, modalHeader, modalFooter, modalContext.tsx)

• ModalContainer: prop isVisibled renamed to isVisible (breaking, same typo-fix pattern as Drawer).
• Animation swapped from framer-motion to plain CSS + onAnimationEnd; adds useScrollLock(isVisible).
• Context (makeInvisible) moved from a bare createContext in Container/index.tsx to a dedicated ModalProvider/useModal() pair in modalContext.tsx (internal — ModalHeader uses it, not the public multi-modal useModal hook from hooks/useModal.ts, which is unrelated and unchanged; same naming collision as Drawer).
• ModalHeader/ModalFooter: no prop changes (showCloseButton, alignment: "left"|"center"|"right"|"between"|"around" all unchanged).
• Public useModal/ModalProvider (multi-modal registry, hooks/useModal.ts + providers/modalProvider.tsx) API is unchanged: same overloads and same { modalIsOpen, modalData, openModal, closeModal, closeAll } shape.

MultiSelect

• onSelect renamed to onChange, now correctly reflects the next-state array (old had a stale-closure bug).
• isError prop removed — now derived internally from errorMessage/fieldErrors[name].
• Adds id, showAsterisk, label, errorMessage, unShowFieldTemplate, orientation. Now uses useForm() + FieldTemplate instead of useFormController().
• Dropdown gains auto-flip positioning and useScrollLock.

Pagination (breaking — router coupling removed)

• Old component called Remix's useNavigate() directly and read page/per_page from the URL via scope/pageKey/perPageKey props — it performed navigation itself.
• New component is a plain controlled component: currentPage is now required (no default), and a new onChange?: (page: number) => void callback replaces the built-in navigation. scope, pageKey, perPageKey props are removed.
• Migration action: any code relying on Pagination auto-updating the URL must now pass currentPage explicitly and implement its own onChange handler (e.g. calling navigate/setSearchParams yourself).

Popover

• No prop changes. framer-motion dependency dropped (was already a no-op fade, duration: 0) in favor of a plain visibility toggle. Adds useScrollLock(isOpen).

Radio (radioBox, radioGroup, radioContext.tsx)

• RadioBox gains isError?: boolean (per-item error override, falls back to group state).
• RadioGroup gains label, showAsterisk, errorMessage, disabled (new group-wide disable — previously only per-box), unShowFieldTemplate, orientation. Now uses useForm()/FieldTemplate instead of useFormController().
• Fix: user-supplied onClick/onFocus on RadioBox are no longer silently clobbered by the internal handler (previously {...rest} spread after the hardcoded handlers wiped out user callbacks).

RichText

• maxLimit default changed from 2000 to 10000 — a consumer relying on the implicit 2000 cap will silently allow far more text now.
• orientation default is "vertical"; gains label, showAsterisk, id, unShowFieldTemplate, baseErrorMessage. Error/label chrome now handled internally via the shared FieldTemplate, replacing manual FormController/FormLabel wrapping.
• Ref handling changed: the hidden <input> no longer accepts/forwards an external ref (previously exposed via useFormController()). Anything relying on grabbing that ref externally will break.
• The hidden input's value is now .slice(0, maxLimit) on the serialized JSON string, not the visible text length — a quirky behavior worth testing against your own content.
• New: video embeds. videoConfig (RichTextInsertVideoProps) + a new InsertVideo toolbar button (YouTube URLs only, extracts ?v= param). New "video" element/mark type. Important asymmetry: the video toolbar button renders whenever not explicitly hidden (no videoConfig required, unlike the image button which requires imageConfig) — add "video" to hiddenButtons if you don't want it. Also, toHtml serializes a video node to <iframe>, but toRichTextValue has no matching deserialize case — video content saved as HTML will not round-trip back into a video block.
• getHtmlFromRichTextValue/getRichTextValueFromHtml renamed to toHtml/toRichTextValue (same signatures).
• isHtml moved out of @arkyn/components entirely, into @arkyn/shared.
• slate/slate-history/slate-react are now peer dependencies (>=0.100.0) instead of bundled dependencies — add them to your own package.json.

Select

• onSelect renamed to onChange, now returns just the value string (deselect calls onChange("")).
• onFocus is now no-arg (was FocusEvent-based).
• searchCountryPlaceholder/searchPlaceholder prop removed — the internal search input no longer accepts a placeholder.
• Gains id, showAsterisk, label, errorMessage, unShowFieldTemplate, orientation. Uses useForm()/FieldTemplate instead of useFormController().
• No public type export — SelectProps is no longer importable (was import type { SelectProps } from "@arkyn/types").
• Dropdown gains auto-flip positioning and useScrollLock.

Slider (+ new useSlider hook)

• disableDrag renamed to disabled.
• Full HTML div attribute passthrough (including className) now supported — wasn't before.
• New useSlider(defaultValue?): [number, setValue] hook — clamped 0–100 state pair designed to pair directly with <Slider>.

Switch

• Gains label, orientation (default "horizontalReverse"), unShowFieldTemplate, showAsterisk, errorMessage. No longer depends on an external FormController context for id/ref (self-sufficient via useId()/useRef).

Table

• No prop or behavior changes beyond path/casing. TableBody's empty-detection is slightly hardened (filters falsy children before counting).

Tabs → tab (+ new CardTab)

• TabContainer: defaultActive renamed to defaultValue, onClick renamed to onChange. Gains disabled (also on TabButton).
• Animated sliding underline removed — replaced by a static CSS ::after bar with no transition between tabs.
• New CardTabButton/CardTabContainer: structurally a near-duplicate of Tab (same props/context shape) but styled as a segmented "pill" control instead of an underlined tab bar — not a Tabs replacement, a separate visual variant.

Textarea (breaking — form-context rework)

• isError prop removed — replaced by derived errorMessage/fieldErrors lookup.
• Gains label, showAsterisk, errorMessage, explicit value/defaultValue typing (controlled + uncontrolled).
• No longer requires being nested inside a FormController — self-contained via useForm() + useId(), wrapped in FieldWrapper/FieldLabel/FieldError internally.

Toast

• The standalone visual Toast component is removed — but this is lower-risk than it sounds: in both v2.2.3 and v3.0.2 the actual rendering was always delegated to react-hot-toast's own <Toaster>/toast.success()/toast.error(); the custom Toast component/CSS was already dead code, exported but never wired into showToast. Deleting it has no runtime effect for anyone using useToast()/showToast() as documented.
• useToast()/showToast({message, type: "success"|"danger"}) API is unchanged.
• GoogleProvider/ToastContext-style separate context files were consolidated into single provider files (providers/toastProvider.tsx), matching the pattern used by Drawer/Modal.

Tooltip

• No prop changes. Gains adaptive positioning (flips top↔bottom/left↔right on viewport overflow via a ResizeObserver-like effect).
• Behavior change: text is now rendered via dangerouslySetInnerHTML (supports inline HTML) instead of as a plain string child — sanitize any dynamic text values yourself if they include user input.

New components

• AudioPlayer — Standalone playback widget extracted from AudioUpload. Props: src (required), disabled, onPlayAudio/onPauseAudio (receive {currentTime, totalTime, formattedCurrentTime, formattedTotalTime}).
• Calendar — Value-bound date picker (type: "single" | "range" discriminated union), variant?: "basic"|"complete", controlled/uncontrolled value/defaultValue/onChange, plus independent viewValue/onChangeView for the displayed month.
• FullCalendar — Multi-view (day/week/month) scheduling/agenda calendar with events (title, date range, scheme, onClick) and blockedTimestamps. Navigation-only — no bound "selected value".
• CardTabButton / CardTabContainer — Segmented "pill" tab control — see Tabs.
• CurrencyInput — See Input family.
• MaskedInput — See Input family.
• FieldError / FieldLabel / FieldWrapper — Generic, context-free form-field primitives used across the library — see Form.
• GoogleAnalytics — GA4 script injector, sibling to GoogleTagManager. Props: measurementId (required), showInDevMode?.

Hooks

• useAutomation — Signature changed from no-args (reading Remix hooks internally) to useAutomation(formResponseData: any) — caller now passes the raw server response instead of the hook reading it via Remix.
• useDrawer — Unchanged API; re-sourced from providers/drawerProvider.
• useModal — Unchanged API; re-sourced from providers/modalProvider.
• useHydrated — Unchanged.
• useScopedParams — Signature changed: useScopedParams(searchString: string, scope?: string) — caller must now pass location.search explicitly (was read internally via Remix's useLocation()).
• useToast — Unchanged.
• useFieldErrors — Removed. Replaced by useForm() (see Form section) — no longer reads Remix hooks automatically; fieldErrors must be passed into FormProvider explicitly.
• useForm (new) — useForm(): { fieldErrors } — reads FormProvider context.
• useScrollLock (new) — useScrollLock(isLocked: boolean): void — locks/restores document.body scroll. Used internally by Modal/Drawer/Popover/Select/MultiSelect dropdowns; also exported for custom overlays.
• useSearchAutomation (new) — useSearchAutomation(searchString: string, scope?: string) — URL-param-driven variant of useAutomation.
• useSlider (new) — See Slider.

Providers

• DrawerProvider — Unchanged behavior/shape, moved provider/ → providers/.
• ModalProvider — Unchanged behavior/shape.
• ToastProvider — Unchanged behavior/shape.
• GoogleProvider → PlacesProvider — Breaking: prop googleMapsApiKey → apiKey; children changed from plain ReactNode to a render-prop (isLoaded: boolean) => ReactNode.
• FormProvider (new) — { children, fieldErrors?, form? } — see Form.

Services (public)

@arkyn/server

Package metadata

• main
  • v2.2.3: ./dist/bundle.js
  • v3.0.2: ./dist/index.js
• exports map
  • v2.2.3: none
  • v3.0.2: ~34 subpath entries
• dependencies
  • v2.2.3: @arkyn/shared, @aws-sdk/client-s3 ^3.782.0, sharp ^0.33.5, zod ^3.24.2
  • v3.0.2: @arkyn/shared, @arkyn/templates only
• peerDependencies
  • v2.2.3: @remix-run/node ^2.16.4
  • v3.0.2: libphonenumber-js >=1.13.7, zod >=4.4.3

Removed exports

• ApiInstance (GET/POST/PUT/PATCH/DELETE, uppercase methods) — conceptually replaced by ApiService (see below), but the shape differs enough to treat as removed + new rather than a rename.
• InboxFlowInstance — removed; replaced by LogService.
• getCaller (standalone function) — replaced by DebugService.getCaller() (static method).
• httpDebug — replaced by flushDebugLogs (env var gate also changed: SHOW_ERRORS_IN_CONSOLE → DEBUG_MODE).

New exports

• ApiService — HTTP client class. new ApiService({ baseUrl, baseHeaders?, baseToken?, enableDebug? }), methods get/post/put/patch/delete(endpoint, { headers?, token?, urlParams?, body? }) (lowercase methods, object-based args, new urlParams templating).
• DebugService — setIgnoreFile(file), clearIgnoreFiles(), getCaller().
• LogService — setConfig({trafficSourceId, userToken, logBaseApiUrl?}), getConfig(), resetConfig().
• flushDebugLogs — env-gated colored debug log printer.
• formAsyncParse — async counterpart to formParse, using safeParseAsync for schemas with async refinements.
• validateCep, validateCnpj, validateCpf, validateDate, validatePassword, validatePhone, validateRg — moved here from @arkyn/shared (see @arkyn/shared).
• validateEmail(rawEmail): Promise<boolean> — genuinely new; format + RFC-5322-ish checks plus a live DNS MX/A/AAAA lookup.

Changed exports (breaking behavior)

• All success-response classes (Created, Found, Updated, Success, NoContent): constructor signature inverted. Old: (body: T, init?: ResponseInit) (status/headers overridable via init). New: (message: string, body?: any) with hard-coded status codes per class and no way to override status/headers. Every call site like new Created(body) must become new Created("message", body).
• UnprocessableEntity: constructor's second enableDebug boolean parameter is removed — debug logging always fires now (env-gated only).
• SchemaValidator<T>: generic constraint T extends Schema (zod v3) → T extends ZodType (zod v4); return type SafeParseReturnType → ZodSafeParseResult. New method formAsyncValidate().
• errorHandler: the fallback 500 now passes the original error as cause (new ServerError("Server error", error)) instead of dropping it.
• validateDate (moved from shared): config.inputFormat literals renamed from "DD/MM/YYYY"|"MM-DD-YYYY"|"YYYY-MM-DD" to "brazilianDate"|"isoDate"|"timestamp".
• validatePhone (moved from shared): now expects compact E.164 input ("+5532912345678") via libphonenumber-js, not the old space-separated "+55 32912345678" format.
• validateCnpj/validateCpf/validatePassword: same signatures, minor hardening (extra length/whitespace guards; validatePassword's special-char regex now also accepts ;).

@arkyn/shared

Package metadata

• main
  • v2.2.3: ./dist/bundle.js
  • v3.0.2: ./dist/index.js
• exports map
  • v2.2.3: none
  • v3.0.2: one subpath per function
• dependencies
  • v2.2.3: uuid ^10.0.0
  • v3.0.2: @arkyn/templates (now correctly declared) — uuid dropped
• peerDependencies
  • v2.2.3: none
  • v3.0.2: libphonenumber-js >=1.13.7 (optional — only if calling formatToPhone/findCountryMask)

Removed exports (moved to @arkyn/server)

New exports

• formatToCapitalizeFirstWordLetter(sentence): string
• findCountryMask(phoneNumber): [string, CountryType] — parses E.164 via libphonenumber-js, resolves the @arkyn/templates country/mask.
• isHtml(rawString): boolean — moved in from @arkyn/components.
• ValidateDateService (class) — low-level date-part/format validation used internally by formatDate/parseToDate.

Renamed exports

• truncateLargeFields → parseLargeFields (same signature/behavior).
• maskSensitiveData → parseSensitiveData (same signature/behavior).
• formatToDate → parseToDate — same signature, but behavior changed: "isoDate" now means MM-DD-YYYY (was YYYY-MM-DD), and the timezone offset sign is flipped (a call with a negative/positive timezone argument returns a different UTC time than before — verify any code passing an explicit timezone).

Changed exports (breaking behavior)

• formatDate: same signature; "isoDate"/"timestamp" literal meanings swapped as above; now throws descriptive errors for invalid calendar dates (e.g. Feb 30) instead of silently producing NaN; date math switched from local-timezone Date construction to explicit Date.UTC, removing a host-timezone-dependent bug but changing output for machines in non-UTC zones.
• formatToCep/formatToCnpj/formatToCpf: error message text changed from generic "Invalid ... format" to descriptive "<Type> must be contain N numeric digits: <value>" — breaking if you pattern-match on the thrown message.
• formatToPhone: fully rewritten. Old expected "+55-32 912345678"-style input; new expects plain E.164 ("+5534920524282") via libphonenumber-js + the new findCountryMask. Old-style input will throw.
• formatToHiddenDigits: options is now optional (was required).
• formatToEllipsis: truncation now breaks at whitespace boundaries and strips trailing punctuation — output can differ from v2.2.3 for the same input.
• calculateCardInstallment: rounding order changed (rounds installmentPrice first, then derives totalPrice) — can shift the returned total by a cent versus v2.2.3 for some inputs.
• stripHtmlTags: now also strips <script>/<style> blocks and HTML comments, not just bare tags.
• generateId: uuid dependency dropped in favor of native crypto.randomUUID()/crypto.getRandomValues() — same overloads/output shape, no uuid transitive dependency anymore.

@arkyn/templates

Package metadata

• main
  • v2.2.3: ./dist/bundle.js
  • v3.0.2: ./dist/index.js
• exports map
  • v2.2.3: none
  • v3.0.2: ./brazilianStates, ./countries, ./countryCurrencies, ./maximumFractionDigits subpaths

New exports

• brazilianStates — new array of 27 {label, value} entries (26 states + Federal District).
• CountryType — new exported type for countries entries.

Changed exports (breaking data shape)

1. The prefix field is removed from every entry (was a nullable string on ~30 NANP +1 territories). Any code reading country.prefix breaks.
2. Brazil's mask changed from a single string to a two-entry array: ["(__) _____-____", "(__) ____-____"]. Code assuming mask is always a plain string (no Array.isArray check) will break specifically for iso === "BR".

// v2.2.3
{ name: "Brasil", code: "+55", prefix: null, iso: "BR", flag: "...", mask: "(__) _____-____" }

// v3.0.2
{ name: "Brasil", code: "+55", iso: "BR", flag: "...", mask: ["(__) _____-____", "(__) ____-____"] }

Removed: @arkyn/types

import type { AlertContainerProps, ButtonProps, InputProps } from "@arkyn/types";

import { Button } from "@arkyn/components/button";
type ButtonProps = React.ComponentProps<typeof Button>;

Removed: @arkyn/newcomponents

• If you were already using @arkyn/newcomponents: migrating to v3 @arkyn/components is close to a drop-in continuation (same prop shape/variant system), aside from the general @arkyn/types removal and Badge's default-size change ("md" → "lg") and the new "secondary" scheme.
• If you were using the old stable @arkyn/components@2.2.3 Badge/Button: treat this as a meaningful internal rewrite (different icon-rendering plumbing) even though the prop surface is largely compatible.

Tooling / packaging changes

• Module format: every package switches from a single bundled CJS/ESM file (dist/bundle.js, no exports map) to unbundled per-module ESM output (dist/index.js + dist/modules/**) with a granular exports map — enabling subpath imports like @arkyn/components/button or @arkyn/shared/formatToCep instead of only importing from the package root.
• Publish scope: the root .npmignore is gone; each package now declares an explicit files allowlist in its own package.json (["dist", "README.md", "LICENSE.txt", ...]). README.md/LICENSE.txt are now bundled in every published tarball (they weren't before).
• Workspaces: root package.json adds apps/* alongside packages/*. apps/development is a new internal Remix/React Router playground app (private: true) — not part of the public package surface.
• Linting: root biome.json (Biome 2.5.1) is new — there was no formal linter/ESLint config in v2.2.3.
• Engines: v3.0.2 packages declare "engines": { "node": ">=18.0.0", "bun": ">=1.0.0" }; v2.2.3 declared none.

Migration checklist

1. Uninstall @arkyn/types and @arkyn/newcomponents from your package.json — neither exists in v3.
2. Install the new peer dependencies your app actually needs: libphonenumber-js (server validators, PhoneInput/CurrencyInput/findCountryMask), mapbox-gl (MapView), zod@^4 (server schema validation — check for v3→v4 breaking changes in your own zod usage), slate/slate-react/slate-history (RichText), lucide-react, react-hot-toast, plus whichever other components you use per the new peerDependenciesMeta table in each package's README.
3. Import a stylesheet: add import "@arkyn/components/styles" (or per-component .css subpath imports) — nothing rendered without a theme/token override before, but the explicit CSS import step is new.
4. Remove all @remix-run/* coupling assumptions: useFieldErrors, useAutomation, useScopedParams, Pagination, and GoogleProvider→PlacesProvider all changed from reading Remix router/action-data hooks internally to taking plain arguments — audit every call site.
5. Replace the old Form/FormController/FormLabel/FormError pattern with FormProvider + useForm() + FieldWrapper/FieldLabel/FieldError, passing fieldErrors in explicitly.
6. Fix the isVisibled → isVisible typo rename on ModalContainer and DrawerContainer.
7. Rename onUpload → onChange on AudioUpload, FileUpload, ImageUpload; onSelect → onChange on Select/MultiSelect; onChangeValue → onChange on CurrencyInput; onClick → onChange and defaultActive → defaultValue on TabContainer.
8. Replace any usage of Breadcrumb, Card, Skeleton, CpfCnpjInput — no direct v3 replacement exists; reimplement manually.
9. Migrate GoogleMap → MapView: swap your Google Maps API key for a Mapbox access token, update the coordinates/marker shape, and drop any reliance on draggable markers.
10. Audit @arkyn/templates countries usage: remove any reads of country.prefix, and guard country.mask against being an array (true today only for Brazil).
11. Re-check date/phone formatting call sites in @arkyn/shared: formatDate/parseToDate's "isoDate" literal now means MM-DD-YYYY; formatToPhone/validatePhone now expect E.164 input.
12. Update HTTP response construction in @arkyn/server: new Created(body) → new Created("message", body) (and equivalently for Found/Updated/Success/NoContent); remove the second enableDebug argument from UnprocessableEntity.
13. If you import any prop type by name from @arkyn/components (e.g. SelectProps, SwitchProps, RadioGroupProps), switch to React.ComponentProps<typeof X> since these are no longer exported.