@thebase/ui 0.0.12 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project are documented in this file.
 
+## [v1.0.0] - 2026-10-03
+
+First stable release. From here on the package follows [Semantic Versioning](https://semver.org/) — see the [Versioning policy](README.md#versioning-policy) for what counts as the public API and what each version bump means. No API changes versus v0.0.12 beyond the fixes below; upgrading from 0.0.12 needs no code changes.
+
+### Changed
+- Docs: production pin examples now use `@1.0.0`, or the `@1` major range to receive non-breaking updates. `docs/owl-components.md` documents the global component fallback below, and `docs/components/button.md` now lists `Button`'s `unstyled`, `attrs`, and `getRef` props.
+- Internal: shared prop and overlay helpers replace per-component copies (`optional()`/`slotProps` prop declarations, controlled-open and Bootstrap Collapse hooks, one binder for the static dialog/sheet/drawer overlays, one checkbox/radio enhancer). Every pure Owl component keeps exactly the same props, and every static adapter keeps the same attributes, events, and `element.BaseUI*` handles.
+
+### Fixed
+- Pure Owl: nested consumer components no longer crash with `Cannot find the definition of component "Icon"` (or `Button`, etc.) when their template uses a BaseUI component missing from their own `static components`. `Component` from `@base/owl` now falls back to the globally registered BaseUI components for every component, not just the root passed to `mount()`. A component's own `static components` entries still take precedence.
+- `Sidebar`: `SidebarMenu` now fills the remaining panel height and scrolls on its own when its items overflow, so a long nav list no longer pushes `SidebarFooter` off-screen.
+
 ## [v0.0.12] - 2026-09-13
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@ The Base UI is a CDN-installable UI kit built with Bootstrap 5 styling and Owl-e
 
 Its strong points: **no build step** — every component runs straight from a CDN `<script>`/import map, nothing to compile; **modular component design** — each component is a self-contained unit you import or mark up individually, not a monolith; **vanilla JavaScript/TypeScript** — no framework lock-in, no JSX, no compiler-specific syntax to learn; and this combination makes it well suited to building **WYSIWYG website builders**, where components must mount, unmount, and re-render dynamically from user-driven markup or drag-and-drop edits rather than a fixed build-time component tree.
 
-Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the `@latest` tag for readability; pin an exact version instead (e.g. `@0.0.11`) for any production page, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:
+Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the `@latest` tag for readability; pin an exact version instead (e.g. `@1.0.0`, or `@1` to take only non-breaking updates) for any production page, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
@@ -58,7 +58,26 @@ Every component ships both APIs from `src/components/<name>/`: the static `b-ui`
 
 ## Release notes
 
-See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current published version: **0.0.11**.
+See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current version: **1.0.0**.
+
+## Versioning policy
+
+From 1.0.0 on, BaseUI follows [Semantic Versioning](https://semver.org/). The public API covered by this promise is:
+
+- Pure Owl component classes, their names, props, slots, and callback props exported from `@thebase/ui`.
+- Static markup: `b-ui`/`b-icon` names, `b-att-*` attributes, and `baseui:*` events.
+- CSS: `bu-*` class names and `--b-*` design tokens.
+- Runtime exports (`BaseUI`, `Component`, `mount`, `xml`, `cn`, `mergeStyle`, theme helpers), including `Component`'s fallback to globally registered BaseUI components, and the published `dist/` file names and package `exports` paths.
+
+What each release type means:
+
+- **Major** (`2.0.0`): removes or renames any of the above, or changes its behavior or default look in a way existing pages must adapt to. Every breaking change is listed under a **Breaking** heading in the CHANGELOG with a migration note.
+- **Minor** (`1.1.0`): new components, props, variants, tokens, or icons — existing code keeps working unchanged.
+- **Patch** (`1.0.1`): bug fixes and visual fixes that don't change the API.
+
+Anything prefixed `_`, undocumented internals, and the `docs/`/`examples/` sources are not part of the public API. Neither are the source-level authoring helpers described in [Component Authoring](docs/component-authoring.md) (`optional()`, `slotProps`, the `open-state.js` hooks, `bindBootstrapOverlay()`): they aren't exported from the package and may change in any release. Deprecated APIs keep working until the next major and are flagged in the CHANGELOG first.
+
+Pinning: use an exact version (`@1.0.0`) when you need byte-identical output, or the major range (`@1` on jsDelivr/unpkg, `^1.0.0` in npm) to receive fixes and features without breaking changes. Avoid `@latest` in production — it will move to the next major.
 
 ## Project Documents