## 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](/guides/page-compositions). |
| 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](/releases/1.0.0) 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

1. Read the entry for your target version in this file and the package changelog.
2. Apply the migrations.
3. Run your test suite.
4. 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.