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
23 changes: 23 additions & 0 deletions changelogithub.config.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import { readFileSync } from 'node:fs'

const { version } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
const notes = 'https://github.com/destyler/ui/blob/v0.0.3/docs/releases/0.0.3.md'

// changelogithub renders this section only for conventional breaking commits.
// Preserve `!` in the 0.0.3 squash subject; do not carry these notices forward.
export default version === '0.0.3'
? {
titles: {
breakingChanges: [
'Breaking Changes',
'',
`Read the [UI 0.0.3 migration notes](${notes}) before upgrading.`,
'',
`- Core 0.3.4 Steps: one roving tab stop, focus-only arrow navigation, and a completion summary that is no longer a tabpanel. [Steps migration](${notes}#steps-keyboard-navigation-and-completion-roles).`,
`- Core 0.3.4 Select: Content owns focus in composite mode; the nested List no longer has a tab stop. [Select migration](${notes}#select-focus-ownership).`,
`- Retained Vue limit: wrapper \`.once.prevent\` may run after core and cannot reliably cancel that core action. Ordinary cancellation only works where core checks \`event.defaultPrevented\`. [Listener limits](${notes}#vue-listener-and-callback-fixes).`,
'',
].join('\n'),
},
}
: {}
6 changes: 3 additions & 3 deletions docs/core-compatibility-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ 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.3. The 2026-10-21 reproduction below
`@destyler/*` package to exact core 0.3.4. 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.3. It does not publish a package or change registry
selection, against core 0.3.4. 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.

Expand Down Expand Up @@ -37,7 +37,7 @@ Dialog-specific gate; this is not an assertion that every beta.17 component fail
## Original beta.17 release-closure checklist

This checklist records the beta.17 replacement plan. The current candidate is
UI 0.0.2 with core 0.3.3; its stable version does not change the verification
UI 0.0.3 with core 0.3.4; its stable version does not change the verification
requirements below or authorize publication by itself.

1. Run the existing lint, framework type checks, test/SSR suites, packed consumer
Expand Down
2 changes: 1 addition & 1 deletion docs/node-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ 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.3 dependency update retains that same Node.js 22.22.3
- The current core 0.3.4 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.

Expand Down
11 changes: 10 additions & 1 deletion docs/release-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,16 @@ title alone: the changelog generation step currently allows failure without
blocking npm publication. Neither a successful publish guard nor an npm publish
confirms that these migration notes reached users.

#### UI 0.0.2: Vue void-element hydration
#### UI 0.0.3: Vue listeners and breaking core accessibility migrations

Include the [0.0.3 release notes and upgrade guidance](releases/0.0.3.md) in the
GitHub release description. All four public packages consume core `^0.3.4` and
receive synchronized UI version 0.0.3. The patch numbers do not imply that no
migration is needed: disclose the Steps keyboard/role and Select focus changes,
and Vue's existing wrapper `.once.prevent` limitation. Require new exact-commit
CI and installed-artifact validation against core 0.3.4 before release.

#### Historical UI 0.0.2: Vue void-element hydration

Include the [0.0.2 release notes and upgrade guidance](releases/0.0.2.md) in the
GitHub release description. This patch fixes Vue SSR hydration mismatches from
Expand Down
106 changes: 106 additions & 0 deletions docs/releases/0.0.3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# UI 0.0.3

## Scope

This release synchronizes the root and all four public `@destyler-ui/*`
packages at 0.0.3 and updates every `@destyler/*` catalog range to `^0.3.4`.
All frameworks consume the new core, not just Vue. Node >=22.22.3 and public
framework peer ranges are unchanged. Historical 0.0.2 notes remain historical.

Core 0.3.4 includes the breaking changes below. A patch version does **not**
mean that no migration is required. See the published
[core 0.3.4 release](https://github.com/destyler/destyler/releases/tag/v0.3.4).

## Breaking core migrations

### Steps keyboard navigation and completion roles

Steps now uses one roving tab stop instead of placing every non-linear trigger
in the Tab sequence. Arrow keys, Home and End move focus without selecting a
step. Enter and Space activate the native trigger button. Review keyboard-order
assertions and custom key handlers. Render one native, enabled, mounted trigger
for every index from zero through `count - 1`; per-trigger native disabling and
partially mounted lists are not supported navigation modes. Review linear,
controlled and RTL behavior.

The completion summary is no longer a `tabpanel` labelled by a nonexistent
trigger. Update role queries and give the summary meaningful content or a
heading. If advancing hides the focused element, move focus appropriately.
See the [core Steps keyboard migration](https://github.com/destyler/destyler/blob/16e22b9336e18b6026aa7f0049a2470ffe65392b/packages/components/steps/docs/steps.mdx#keyboard-navigation).

### Select focus ownership

In default composite mode, focus belongs to Content, which owns the listbox
role and active-descendant relationship; its nested List no longer has a tab
stop. Move List-specific focus styling and imperative focus assumptions to
Content, or review explicit custom focus overrides. Non-composite mode retains
the List tab stop. See the [core Select focus migration](https://github.com/destyler/destyler/blob/16e22b9336e18b6026aa7f0049a2470ffe65392b/packages/components/select/docs/select.mdx#focus-ownership).

## Vue listener and callback fixes

Steps and Select now run ordinary caller listeners before core handlers,
including `asChild`, while preserving listener arrays and deduplication.
Steps Root forwards change callbacks through its Vue emits contract. Listener
replacement, refs, attributes, and existing controlled behavior are covered by
the focused regressions.

Ordinary caller cancellation can prevent core behavior only when the core
handler checks `event.defaultPrevented`. This is not a new universal veto
contract: focus and pointer handlers that do not check it retain their existing
behavior. Wrapper `.once.prevent` may run after core and therefore cannot be
relied on to cancel that core action. Capture and passive semantics are
unchanged. Review cancellation-sensitive compositions explicitly.

## Upgrade

Explicitly install `@destyler-ui/*@0.0.3` (or `^0.0.3`) for each framework in use
and refresh the application lockfile. The range `^0.0.2` excludes `0.0.3`.
Keep multiple UI framework packages synchronized. Core's `^0.3.3` range already
permits 0.3.4 on a fresh resolution; an existing frozen lockfile does not update
itself. Test keyboard navigation, focus styles, completion role queries,
controlled callbacks, SSR/hydration, and cancellation-sensitive listeners in
your application after upgrading.

## Validation and limits

The Vue patch adds 320 Happy DOM unit regressions. Earlier PR #169 CI passed
7,578 tests with 48 skipped per Node matrix entry, including the existing
Chromium Steps (27) and Select (46) cases. Those results belong to the earlier
wrapper candidate, not the final UI 0.0.3/core 0.3.4 integration.

Before release, the final commit must pass the normal CI, packed-consumer,
exact-core compatibility, documentation, and browser checks with real core
0.3.4 registry artifacts. The exact-core gate is now pinned to 0.3.4. Neither
Happy DOM results nor the bounded existing browser cases establish exhaustive
browser or assistive-technology coverage. No new broad accessibility guarantee
is made.

## Release-note generation

Preserve a conventional breaking squash subject, such as
`chore(release)!: prepare UI 0.0.3 with core 0.3.4`, with a
`BREAKING CHANGE:` footer describing the Steps and Select migrations. The repository's
`changelogithub.config.mjs` uses the supported `titles.breakingChanges` option
so the generated GitHub release body includes the migration links and the
retained Vue cancellation limit alongside the normal generated sections.
Without a breaking commit in the release range, changelogithub omits this
section. The configuration is scoped to package version 0.0.3 so later releases
do not repeat these notices automatically.

The release-preparation render check uses the actual generator without invoking
its publishing CLI, resolving contributors, or accessing GitHub. Install it
outside this repository with lifecycle scripts disabled, then run:

```sh
proof_dir=$(mktemp -d)
npm install --prefix "$proof_dir" --cache "$proof_dir/cache" \
--ignore-scripts --no-audit --no-fund changelogithub@15.0.5
CHANGELOGITHUB_TEST_ROOT="$proof_dir" node --test scripts/test-release-notes.mjs
```

This verifies automatic config discovery, rendered migration URLs, Steps and
Select breaking disclosures, retained `.once.prevent` limits, and preservation
of ordinary feature, fix, performance, and comparison sections. The workflow's
unpinned `npx changelogithub` and `continue-on-error` behavior are unchanged;
check the generated release body after publication. This local proof does not
claim that the future GitHub release job has succeeded.
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 current lockfile resolves `@destyler/tabs@0.3.3`, 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).
The current `@destyler/tabs` dependency range is `^0.3.4`, 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
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@destyler-ui/monorepo",
"version": "0.0.2",
"version": "0.0.3",
"private": true,
"packageManager": "pnpm@10.28.0",
"description": "",
Expand Down
2 changes: 1 addition & 1 deletion packages/react/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@destyler-ui/react",
"type": "module",
"version": "0.0.2",
"version": "0.0.3",
"packageManager": "pnpm@10.28.0",
"description": "Build scalable design systems with unstyled, accessible UI components.",
"author": "Elone Hoo <hi@elonehoo.me>",
Expand Down
2 changes: 1 addition & 1 deletion packages/solid/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@destyler-ui/solid",
"type": "module",
"version": "0.0.2",
"version": "0.0.3",
"description": "Build scalable design systems with unstyled, accessible UI components for Solid",
"author": "Elone Hoo <hi@elonehoo.me>",
"license": "MIT",
Expand Down
2 changes: 1 addition & 1 deletion packages/svelte/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@destyler-ui/svelte",
"type": "module",
"version": "0.0.2",
"version": "0.0.3",
"description": "Build scalable design systems with unstyled, accessible UI components for Svelte",
"author": "Elone Hoo <hi@elonehoo.me>",
"license": "MIT",
Expand Down
11 changes: 10 additions & 1 deletion packages/vue/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,14 +76,23 @@ const checked = ref<Checkbox.CheckedState>(false)

Choose controlled or uncontrolled ownership on the first render and keep it stable. A defined `checked`, including `false`, takes precedence over `defaultChecked`; an omitted or `undefined` live prop starts uncontrolled. Do not use the removed `*.controlled` flags. Other components may use the default `v-model` or a different named model; check the component's API.

## Steps and Select migration in 0.0.3

UI 0.0.3 fixes Steps and Select listener composition, including `asChild`,
and Steps Root callback forwarding, and consumes core `^0.3.4`. Review the breaking Steps
keyboard/role and Select focus migrations even though these are patch versions.
Wrapper `.once.prevent` may still run after core; capture/passive behavior is
unchanged. See the [0.0.3 release notes](../../docs/releases/0.0.3.md) for limits
and upgrade guidance. Update explicitly to `0.0.3` or `^0.0.3`: `^0.0.2` excludes it.

## Server rendering and hydration

Version 0.0.2 fixes hydration warnings caused by forwarded slot fragments inside
native HTML void elements such as `input` and `hr`. These elements do not render
default slot children. Non-void elements, custom components and `asChild`
composition retain their slot behavior.

Update explicitly to `0.0.2` or `^0.0.2`: `^0.0.1` does not include this patch.
The hydration fix first shipped in `0.0.2` and remains in `0.0.3`.
See the [0.0.2 release notes](../../docs/releases/0.0.2.md).

## Guides
Expand Down
2 changes: 1 addition & 1 deletion packages/vue/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@destyler-ui/vue",
"type": "module",
"version": "0.0.2",
"version": "0.0.3",
"description": "Build scalable design systems with unstyled, accessible UI components",
"author": "Elone Hoo <hi@elonehoo.me>",
"license": "MIT",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ function mount(render: () => VNode, onError?: (error: unknown) => void) {
}

function connectedApi(send: Send) {
// These are the published core 0.3.3 handlers, not replacement behavior.
// These are the actual core handlers, not replacement behavior.
// No second machine is started: this suite isolates wrapper composition.
return core.connect(core.machine({
id: 'select-listener-contract',
Expand Down Expand Up @@ -365,7 +365,7 @@ describe('select ordinary same-key listeners with connected core handlers', () =
})

describe('select Content self-target keyboard semantics', () => {
// In core 0.3.3 isSelfTarget means containment, not target === currentTarget.
// In core isSelfTarget means containment, not target === currentTarget.
// Real bubbling descendants therefore navigate just like the content itself.
it.each(childKinds)('%s: preserves core navigation for contained descendants and the content itself', (childKind) => {
const control = controls.find(control => control.component === Select.Content)!
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ type Send = Parameters<typeof core.connect>[1]
type MachineEvent = Parameters<Send>[0]

function connectedApi(send: Send) {
// The actual core 0.3.3 click handlers, without starting a second machine.
// The actual core click handlers, without starting a second machine.
return core.connect(core.machine({ id: 'listener-contract', count: 3, defaultStep: 1 }).getState(), send, normalizeProps)
}

Expand Down Expand Up @@ -297,10 +297,10 @@ describe('steps click listener composition with real connected core handlers', (
}
})

describe('steps Trigger keyboard wiring only (not core 0.3.3 keyboard functionality)', () => {
describe('steps Trigger keyboard wiring only (not core keyboard functionality)', () => {
it.each(['ArrowRight', 'ArrowLeft', 'ArrowDown', 'ArrowUp'])('allows a caller to veto a supplied %s handler before movement', async (key) => {
// Core 0.3.3 has no trigger keydown handler. This deliberately supplied
// provider handler tests wrapper composition, not a new keyboard feature.
// This deliberately supplied provider handler tests wrapper composition,
// not the actual core keyboard navigation implementation.
const order: string[] = []
const movement = vi.fn((_key: string) => order.push('movement'))
const base = connectedApi(vi.fn())
Expand Down
Loading
Loading