Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 172 additions & 0 deletions docs/core-032-react-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# React migration to core 0.3.2

This note records the UI source audit and focused validation on 2026-10-31,
starting from UI main `2c7c0ba` and core `v0.3.2` (`53200b44`). It is not a
release announcement or a claim that all supported environments have passed.
The core catalog minimum and the installed-artifact compatibility gate now
require 0.3.2. Previously published UI artifacts are unchanged.

## Contract change

[Core #362](https://github.com/destyler/destyler/pull/362) replaces implicit
property-read tracking in React `useMachine` / `useActor` with subscription to
every changed immutable snapshot. An unchanged snapshot retains its reference;
unchanged nested data retains structural sharing. Render-time property reads,
including those skipped by the React Compiler, no longer determine updates.

Core also exposes `useService` for lifecycle without snapshot subscription and
`useSelector` for explicit selection/equality. Adding a selector beside an
existing `useMachine` subscription does not narrow that existing subscription.
UI does not convert its entire public context API to selectors in this change.

The important migration rule is to avoid treating a complete snapshot or a
freshly connected API object as a semantic effect dependency. An effect that
writes an event can itself trigger the next snapshot notification.

## Reproduced UI impact

The controlled A/B used the actual UI source, React 19.3.0, Happy DOM and the
React Compiler targeting React 18. Component machines were held at core 0.3.2;
only the React adapter switched between published 0.3.1 and 0.3.2. This isolates
adapter behavior, rather than representing a complete old-core installation.
Tour and FileUpload machine sources were unchanged between the two tags, as
were the relevant store/xstate implementation sources. The installed old/new
store bundles were byte-identical.

| Actual UI path / operation | Adapter 0.3.1 | Adapter 0.3.2 before fixes |
| --- | --- | --- |
| `useTour` with the Basic example's whole-API effect calling `start()` | Settled after 4 starts | Reached the fixture's 8-start protection limit; 10 effects/renders |
| `ItemPreviewImage`, same File, three `openFilePicker()` metadata events | 0 additional object URLs | 3 additional URLs and 3 additional revocations |

The A/B logs contained the expected assertion failures, not additional unhandled
errors. The Tour probe deliberately bounds writes: it demonstrates feedback
retriggering, not an observed unbounded browser hang. The preview probe counts
URL creation/revocation; it does not demonstrate a leak, visible flicker or
image-loading behavior. Its observation host opts out of compilation, while the
actual UI components retain compilation.

### Corrections

- **Shared `hooks/use-machine.ts`:** return the core result without spreading
the snapshot. The old workaround manufactured a different root object on
prop-only renders, defeating the new stable-reference contract. Remove its
obsolete read-tracking explanation and compiler opt-out as well.
- **Tour Basic:** keep `tour.start` in a ref updated by an earlier effect and
run startup only on mount, not on every connected API change. This uses only
public React hooks so the displayed documentation source is copyable; it does
not require exporting the internal `useEvent` helper.
- **FileUpload preview:** make URL creation stable for the owning window and
key the resource effect to the actual File and creation function. A window
change still invalidates the resource; cleanup revokes the URL using the
window that created it. Public calls resolve the latest root getter at call
time, including changes without a render. Do not retain an old snapshot's
environment closure.

The shared-hook regression was run red then green: the old clone failed
reference equality after a prop-only render; the fix preserves snapshot, send
and service identities while still receiving metadata-only and context updates,
without requiring snapshot field reads during render.

The final Tour regression mounts the actual Basic example, covers ordinary and
StrictMode mounts, and checks that dismissal stays closed. Its instrumentation
wraps the real hook with a counted/bounded `start` and creates an extra API
object. That is useful regression protection, but the unmocked A/B above—not
this instrumentation alone—is the evidence attributing the change to #362.

## Concurrent-render boundary

A later review found that using the internal render-updated `useEvent` ref for
URL environment resolution exposed a speculative environment through an API
retained by the committed tree. A suspended transition could therefore allocate
an object URL in the wrong window even though the visible tree never changed.

The URL helper now publishes only the committed root getter in an insertion
effect, before descendant layout effects. The insertion effect stores a function
reference only: it does not access DOM nodes or schedule state. Resource calls
still evaluate that getter at call time, so mutable getters do not require a
render. Suspended and aborted renders cannot publish their getters. Cleanup
continues to revoke each URL in the window that created it. This is deliberately
local to FileUpload; the general `useEvent` hook is not changed here.

Two regressions cover suspended transitions followed by abort or successful
commit, saved API calls during suspension and afterward, and a descendant layout
effect calling the helper after commit. They also preserve the existing live
getter, same-window getter replacement and resource-lifetime tests.

## Existing boundaries that should be preserved

Full subscription does not mean every context synchronization becomes a loop.
Core's prop-to-context synchronization still checks deep equality before writing.
UI Select, Combobox and Tree collection effects depend on `collection`, not the
entire snapshot/API. Presence already uses stable `useEvent` and
`[service, setNode]` dependencies. Menu registration and ScrollArea default-scroll
initialization use mount-only effects. Native-input reconciliation drains its
pending queue and consults live service state. Static review found no new defect
in these boundaries; this is not a claim of complete browser validation.

Keep the existing controlled-value guards: omitted values must
not accidentally become controlled or overwrite machine-owned state. These
source-level safeguards are not a guarantee that all possible consumer effects
are safe.

Do not replace existing guards with whole-API effect dependencies, suppress
notifications globally, or compare an entire connected API solely by its value
array. Connected handlers also capture focus, disabled state, translations,
ARIA state and environment information.

## Performance risks, not measured regressions

Signature, Slider, OTP, Carousel, Timer and Toast place broad connected APIs in
ordinary React contexts. More snapshot notifications can propagate to context
consumers; pointer movement and timer ticks deserve particular attention.
Signature and Timer import the core hook directly, so the shared-wrapper fix
alone does not narrow their subscriptions.

This audit has not measured a UI-wide render multiplier, CPU regression or
memory regression. The previous spreading wrapper already observed enumerable
root metadata through the old proxy, so not every metadata notification is new.
Carousel's `Array.from(pageSnapPoints)` allocation also predates 0.3.2.

If profiling justifies narrower boundaries, compare old adapter + original UI,
new adapter + original UI, and new adapter + fixed UI. Count renders and commits
separately, preserve all consumed selector dependencies, and test public API and
context compatibility before changing architecture. Core benchmark ratios are
not measurements of these UI components.

## Validation snapshot and remaining gates

Focused checks so far:

- React 19.3.0: the three new regression files pass 10 tests (Tour 2, FileUpload 7,
shared hook 1); all 11 original React SSR files pass 87 tests.
- React 18.0.0: the same 10 new regression tests pass, plus the original FileUpload
SSR test (1).
- React 19 controlled-state migration: 153 tests pass under Happy DOM. Browser-
specific branches are skipped there; this is not 153 browser-test passes.

These run against installed core 0.3.2 and actual UI source, not the unrelated
older installed workspace. They do not replace the full repository suite or
installed public artifacts.

The fresh frozen workspace install passed with pnpm 10.28.0. All four framework
source type checks passed. Actual repository SSR checks passed 487 tests
(React 87, Vue 168, Solid 90, Svelte 142), and Vue unit checks passed 263 tests.
On Node 22.22.3 the final React targeted run passed 167 tests: 10 new regressions,
153 controlled-state migration tests and 4 existing environment-boundary tests;
the 87 React SSR tests also passed again. These remain simulated-DOM/Node checks.
The lockfile was generated by pnpm, not manually edited: besides core upgrades,
it re-resolved existing non-core peer snapshots without changing their package
versions or integrity entries. The fresh frozen install verifies consistency.

Full workspace lint passed with 0 errors and 667 warnings. The final Node-floor
packed-consumer matrix also passed: all four packages built, packed and installed
into isolated consumers, 52 interaction cases passed, and every resolved core
package was verified as 0.3.2. Its runner unit tests passed 14 cases.
The separate React packed-consumer gate also passed on Node 22.22.3 for React
18.0.0 and 19.3.0: imports, Bundler/NodeNext types, SSR, and simulated-DOM
hydration/interactions. Its declaration-transform unit tests passed 4 cases.

Real-browser and Storybook verification has not completed. Do not infer Chromium/Firefox/WebKit interaction, focus, layout,
accessibility, hydration or browser resource behavior from Happy DOM/SSR passes.
The complete lint, type, framework, packed-consumer and browser gates remain
required for a release; see the [compatibility checklist](core-compatibility-release.md).
7 changes: 4 additions & 3 deletions docs/core-compatibility-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@ policy remains separately tracked in [core #353](https://github.com/destyler/des
## Current installed-artifact gate

`pnpm test:core-compat` builds the current checkout and pins every resolved
`@destyler/*` package to exact core 0.3.1. The 2026-10-21 reproduction below
`@destyler/*` package to exact core 0.3.2. The 2026-10-21 reproduction below
records published beta.17 with core 0.2.13. A passing current gate shows the
workspace Dialog, Popover, and Menu open-state cases, plus Tabs nullable
selection, against core 0.3.1. It does not publish a package or change registry
dist-tags.
selection, against core 0.3.2. It does not publish a package or change registry
dist-tags. See the [React 0.3.2 migration audit](core-032-react-contract.md)
for the snapshot contract, focused evidence and remaining verification limits.

## Reproduced on 2026-10-21

Expand Down
2 changes: 2 additions & 0 deletions docs/node-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ Restoring Node 20 support is not planned for UI or core.
([destyler/destyler#360](https://github.com/destyler/destyler/pull/360)). See the
[core Node support guide](https://github.com/destyler/destyler/blob/main/document/src/content/guide/node-support.mdx)
for consumer requirements and the separate repository-tooling range.
- The current core 0.3.2 dependency update retains that same Node.js 22.22.3
minimum; it does not broaden or narrow the UI Node support policy.
- These migrations do not change previously published UI or core artifacts.

## Upgrade an application
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/overview/tabs-nullable-migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Vue's public `modelValue`, `defaultValue`, `valueChange` and `update:modelValue`

## Core dependency boundary

The pinned `@destyler/tabs@0.3.1` includes the [core correction](https://github.com/destyler/destyler/pull/208) that shipped in 0.2.12 and remains in [core 0.3.1](https://github.com/destyler/destyler/releases/tag/v0.3.1): `clearValue()` and deselectable user activation report `{ value: null }`, and `ValueChangeDetails.value` is `string | null`. This includes clicking the selected trigger and pressing Enter on it in manual activation mode. Vue's `valueChange` payload is that core `ValueChangeDetails` type. React, Solid, and Svelte `onValueChange` handlers use the same payload. See [core #353](https://github.com/destyler/destyler/issues/353) and the [Tabs migration guide](https://github.com/destyler/destyler/blob/v0.3.1/packages/components/tabs/docs/tabs.mdx#migration-nullable-value-change-notifications) from [#356](https://github.com/destyler/destyler/pull/356).
The current lockfile resolves `@destyler/tabs@0.3.2`, which includes the [core correction](https://github.com/destyler/destyler/pull/208) that shipped in 0.2.12 and remains in [core 0.3.2](https://github.com/destyler/destyler/releases/tag/v0.3.2): `clearValue()` and deselectable user activation report `{ value: null }`, and `ValueChangeDetails.value` is `string | null`. This includes clicking the selected trigger and pressing Enter on it in manual activation mode. Vue's `valueChange` payload is that core `ValueChangeDetails` type. React, Solid, and Svelte `onValueChange` handlers use the same payload. See [core #353](https://github.com/destyler/destyler/issues/353) and the [Tabs migration guide](https://github.com/destyler/destyler/blob/v0.3.2/packages/components/tabs/docs/tabs.mdx#migration-nullable-value-change-notifications) from [#356](https://github.com/destyler/destyler/pull/356).

A controlled parent still owns the selection. Accept a clear request by writing `null` back, keep the current value to veto it, or apply the requested value later. Repeated clear requests while a non-null value remains controlled notify again; after the parent accepts `null`, another `clearValue()` is a no-op. Parent writes do not echo a value-change notification. Uncontrolled Tabs update their own selection and report the change.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,13 @@ export const FileUploadItemPreviewImage = forwardRef<HTMLImageElement, FileUploa
const [url, setUrl] = useState<string>('')
const fileUpload = useFileUploadContext()
const itemProps = useFileUploadItemPropsContext()
const { createFileUrl } = fileUpload
const { file } = itemProps
const mergedProps = mergeProps(fileUpload.getItemPreviewImageProps({ ...itemProps, url }), props)

useEffect(() => {
return fileUpload.createFileUrl(itemProps.file, url => setUrl(url))
}, [itemProps, fileUpload])
return createFileUrl(file, url => setUrl(url))
}, [file, createFileUrl])

if (!url)
return null
Expand Down
26 changes: 24 additions & 2 deletions packages/react/src/components/file-upload/hooks/use-file-upload.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import type { PropTypes } from '@destyler/react'
import type { Optional } from '~/types'
import { getDocument } from '@destyler/dom'
import * as fileUpload from '@destyler/file-upload'
import { normalizeProps, useMachine } from '@destyler/react'
import { useId } from 'react'
import { useCallback, useId, useInsertionEffect, useRef } from 'react'
import { useFieldContext } from '~/components/field'
import { useEvent } from '~/hooks/use-event'
import { useEnvironmentContext, useLocaleContext } from '~/providers'
Expand Down Expand Up @@ -37,5 +38,26 @@ export function useFileUpload(props: UseFileUploadProps = {}): UseFileUploadRetu
}

const [state, send] = useMachine(fileUpload.machine(initialContext), { context })
return fileUpload.connect(state, send, normalizeProps)
// URL resources belong to their window, not to a changing machine snapshot.
// Resolve the current environment rather than retaining a connect closure over
// an older snapshot. Do not access the default document during server rendering.
const ownerWindow = typeof window === 'undefined'
? undefined
: getDocument(context.getRootNode?.() ?? document).defaultView ?? window
// Publish only committed environments. A suspended render must not redirect
// an API retained by the visible tree. Insertion effects run before consumers'
// layout effects, while mutable root getters are still resolved at call time.
const committedRootNode = useRef(context.getRootNode)
useInsertionEffect(() => {
committedRootNode.current = context.getRootNode
}, [context.getRootNode])
const resolveOwnerWindow = useCallback(() => getDocument(committedRootNode.current?.() ?? document).defaultView ?? window, [])
const createFileUrl = useCallback<UseFileUploadReturn['createFileUrl']>((file, cb) => {
const win = resolveOwnerWindow() ?? ownerWindow ?? window
const url = win.URL.createObjectURL(file)
cb(url)
return () => win.URL.revokeObjectURL(url)
}, [ownerWindow, resolveOwnerWindow])

return { ...fileUpload.connect(state, send, normalizeProps), createFileUrl }
}
Loading
Loading