Migration and deprecation policy

Every breaking change, and the path from the version that had it.

The policy in force from 1.0

From 1.0 onward, AsheeUI follows semantic versioning for its public API, and a breaking change follows the process below rather than arriving unannounced.

Step	What happens
Deprecation	The API keeps working and carries a deprecation notice that names its replacement and appears in the changelog and in the editor
Window	A deprecated API stays for at least one minor release, so a consumer always has a release to migrate in
Removal	Removal happens only in a major release, and the release notes list every removed API with its replacement
Documentation	Every deprecation and every removal is described here, in this file

Bug fixes, internal refactoring, non-breaking additions and behavioural corrections are not breaking changes and follow the ordinary release flow. A behavioural correction that a consumer could depend on is called out in the release notes.

What counts as the public API

Included	Not included
Everything exported from `@asheeui/web`	Internal modules and helpers
Props, types and component names	DOM structure that is not documented
The configuration keys and their defaults	Class names the framework applies
The CLI's commands, flags and exit codes	The CLI's console output

2.2.0

The library is split into four packages, and the components move out of the asheeui name into the renderer that owns them:

Before	After
The components in `asheeui`	`@asheeui/web`, the DOM renderer
`@asheeui/shared`	`@asheeui/core`, the platform-neutral layer
`asheeui`	`asheeui`, the umbrella entry point
`asheeui/styles`	`@asheeui/web/styles`
`asheeui/puck`	`@asheeui/puck`, the Puck integration

The umbrella entry point is scoped like the rest of the family rather than named after the library: asheeui resolves to @asheeui/web in a browser bundle and to @asheeui/native under Expo and Metro, so one import names a component once and renders on both platforms without a second specifier. An existing "asheeui" dependency is replaced by "asheeui"; the unscoped asheeui name is deprecated in this release and points at this file. A stylesheet imported from asheeui is the other change to make, that subpath moved to @asheeui/web, and the Puck integration is a third, because it is now a package of its own rather than a subpath of a renderer.

The Puck integration moved because it is used on both platforms, and a subpath of the web package could not be. @asheeui/puck has one entry point and two renderers: on the web it is the editor's block registry and the editor's page renderer, and under Metro it is the same block specs plus a renderer that draws a stored page with the native components. @puckeditor/core remains an optional peer, needed by the web half alone. An application that composed pages with asheeui/puck renames that import and needs no other change; @asheeui/web/puck was never published, so no deprecation window applies.

Installing @asheeui/web brings @asheeui/core with it, so an application that imports only the components of one platform installs one package. Add @asheeui/core yourself only if you import its contracts, tokens or configuration utilities directly, and add @asheeui/native for the React Native components.

Nothing else changes: asheeui.config.ts keeps its name, the CLI keeps its asheeui command, the component names, the props and the configuration keys are the same, and the stylesheet still extends the Tailwind theme in the same order.

2.0.0

No public API was removed, renamed or restructured in 2.0.0: every component, prop, type and configuration key from 1.1.x still works, and every addition is opt-in. The release is major because the system it describes is substantially larger, not because a consumer has to change code.

Change	Kind	What to do
`SidebarLayout` renders its shell as a column at every width, so its header and its footer span the page	Behavioural correction. The shell used to become a row at the `lg` breakpoint, which placed the header and the footer beside the columns instead of above and below them.	Check a page above 1024 pixels. If you compensated for the old behaviour with `className`, remove the compensation.
`Chip` takes `closeLabel` for its remove control's accessible name	Additive. The default is still "Remove chip".	Nothing required. Pass `closeLabel` in a list of chips, so each remove control says what it removes.
`EmptyState` takes `actions` for actions that carry a React handler	Additive.	Nothing required. Prefer it over putting a handler inside a configured action, which was never supported.
Ten new components: `Centered`, `Split`, `MarketingLayout`, `DocsLayout`, `SearchInput`, `Stepper`, `DataTable`, `FileUpload`, `LoadingState`, `ErrorState`	Additive.	Nothing required. The layout layer and the compositions are documented in Layouts.
The native package gains a layout kit and a component set	Additive, and in a package of its own.	Nothing required. The web package's API is untouched.

Breaking changes before 1.0

0.8.0 was versioned internally but never published, and the 0.9.x release stage the plan described was folded into 1.0.0, so a consumer on the previous release upgrades from 0.7.0 straight to 1.0.0. The 1.0.0 upgrade guide is the complete picture of that jump; the tables below are the per-version record.

The 0.x releases stabilized the API, and each breaking change arrived with the migration it needed. They are listed here so an upgrade from an earlier release is a documentation exercise rather than an investigation.

`0.8.0`

Change	Migration
`Select` renamed to `Dropmenu`	Rename the import, the element and the props type
`DatePicker` renamed to `Calendar`	Rename the import, the element and the props type
`TextArea` renamed to `Textarea`	Rename the import, the element and the props type
Renamed configuration sections: `components.select`, `components.datePicker`	Use `components.dropmenu` and `components.calendar`
Built-in defaults changed to a boxy radius and a faded fill (`defaultRadius: "xs"`, `defaultVariant: "faded"`)	Pass the previous values in your configuration if you prefer the old look
The substitution API unified on `component` and `componentProps`	Rename `linkComponent`/`linkProps` on `Link`, `props` on `Image`, `imageProps` on `Avatar`, and the same keys on a `Breadcrumb` step and in the `Card` image and link configuration. `Form` gained the pair.
Internal helpers removed from the package root: `getInitials`, `getPaginationRange`, `RadioContext`, `RadioContextValue`, `useRadioGroupContext`	Stop importing them; the components use them internally

`1.0.0`

No public API was removed to reach 1.0. The API that ships with 1.0 is the frozen surface: from here on, the policy above applies.

`1.1.0`

No public API changed. This release is additive:

Addition	Notes
17 components across the layout, pattern, page and utility layers	New exports; every existing import keeps working
New configuration sections (`container`, `section`, `stack`, `grid`, `page`, `sidebarLayout`, `authLayout`, `hero`, `cta`, `featureGrid`, `testimonials`, `pricingCard`, `navbar`, `footer`, `emptyState`, `pinInput`, `clipboard`)	New keys; an existing configuration needs no change
The `asheeui/puck` entry point	New subpath export, and `@puckeditor/core` is an optional peer dependency, so it is only installed when the integration is imported
A shared spacing scale (`Space` and its class maps)	New exports
`resolveConfigCascade`	New utility export; `resolveCascade` is unchanged

Two behavioural notes, neither of which changes an existing component:

PinInput reports a dense code: deleting a character in the middle moves the characters after it left, and a paste into a box beyond the filled characters lands at the end of them. Both are documented in the component's own doc comments.
EmptyState carries no live-region role by default. A consumer that renders it in response to an asynchronous result passes role="status" or role="alert".

Upgrading

Read the entry for your target version in this file and the package changelog.
Apply the migrations.
Run your test suite.
If the change involved the stylesheet import, the provider or the configuration keys, run npx asheeui doctor to confirm the setup.

Reporting a problem with this policy

If a documented migration does not work, or a change arrived without the migration it needed, open an issue. That is treated as a defect in the release, not as a documentation gap.