@octanejs/base-ui 0.1.50 → 0.1.52

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,47 @@
+# Migrating to the Base UI 1.8 binding
+
+This binding targets `@base-ui/react` 1.8.0 and `@base-ui/utils` 0.4.0 through the companion `@octanejs/base-ui-utils` package. Upstream 1.8 parity does not by itself preserve the previously published Octane binding surface.
+
+## Required Octane versions
+
+`@octanejs/base-ui`, `@octanejs/base-ui-utils`, `@octanejs/shadcn`, and `@octanejs/testing-library` now peer on **Octane `^0.2.5`**.
+
+Published Octane **0.2.4 and earlier** is not enough:
+
+- `@octanejs/testing-library` statically imports `isInActScope`, which 0.2.4 does not export.
+- The Base UI 1.8 source needs the compiler and runtime from this release (method and transitive hook compilation, typed namespaces, act batching, layout cascades, fragment portals, and resolved Suspense hydration).
+
+Upgrade Octane in the same release as these bindings. Other `@octanejs/*` packages still accept `^0.1.51 || ^0.2.0` unless they pull in the packages above.
+
+## Newly added APIs
+
+- Select, Combobox, Autocomplete, Drawer, Navigation Menu, OTP Field, Scroll Area, Toolbar
+- Temporal adapters (`date-fns` and `luxon` remain optional peers)
+- `@octanejs/base-ui-utils` public utility entries, including the public store entry
+- Octane `isInActScope` for testing helpers
+
+## Replaced implementations
+
+- Existing primitives are now upstream-shaped authored source with compiler-assigned hook slots, not the previous flat/manual-slot port
+- The package export map is an explicit entry list instead of a wildcard
+- Publication is authored Octane source only; the consuming application compiles it
+
+## Removed APIs and entry points
+
+- Precompiled CommonJS export conditions
+- The previous `./*` wildcard export map. Import only documented public subpaths
+- Previously exposed private Utils implementation paths. Import store utilities, including `StoreInspector`, from the public store entry
+
+## Compatibility retained from the previous Octane binding
+
+These remain supported even though upstream 1.8 no longer documents them on the root barrel:
+
+```ts
+import { useMediaQuery } from '@octanejs/base-ui';
+
+const wide = useMediaQuery('(min-width: 600px)');
+```
+
+`useMediaQuery(query)` still accepts an omitted options argument. The hook also remains at `@octanejs/base-ui/unstable-use-media-query`.
+
+Named component aliases for Accordion, Collapsible, and Tabs, popup handle constructors and factories, toast manager helpers, and the Tabs value/orientation/activation-direction types remain available from their previous root and component subpaths.

package/README.md

@@ -11,10 +11,16 @@ npm install @octanejs/base-ui
 pnpm add @octanejs/base-ui
 ```
 
-Alpha, in progress. Ported at full fidelity from the pinned `mui/base-ui` source
-(`v1.6.0`), proven by differential parity tests against the real
-`@base-ui/react`. See `docs/base-ui-migration-plan.md` for the phased plan
-and progress.
+This binding targets Base UI **1.8.0**. The complete export surface is implemented,
+including Select, Combobox, Autocomplete, Drawer, Navigation Menu, OTP Field,
+Scroll Area, and Toolbar. It peers on **Octane `^0.2.5`**; see
+[MIGRATION.md](./MIGRATION.md) for added, replaced, and removed surfaces.
+Pristine and native unit, browser, type, and hydration checks pass;
+see [UPSTREAM.md](./UPSTREAM.md) for the pinned source and evidence.
+
+Use it in an Octane application with the Octane compiler enabled. ES module
+exports ship authored source so the application compiler selects client or server
+output. Compile these source entries with the consuming application’s Octane toolchain.
 
 ## API
 
@@ -24,11 +30,60 @@ Mirrors Base UI's deep-subpath imports:
 import { Separator } from '@octanejs/base-ui/separator';
 import { useRender } from '@octanejs/base-ui/use-render';
 import { mergeProps } from '@octanejs/base-ui/merge-props';
+import { Select } from '@octanejs/base-ui/select';
+import { Combobox } from '@octanejs/base-ui/combobox';
 ```
 
-Every component takes Base UI's universal composition props — `render` (a JSX element or
+Rendered component parts support Base UI's composition props — `render` (a JSX element or
 `(props, state) => element`), `className` (string or `(state) => string`), and `style`
 (object or `(state) => object`) — routed through `useRenderElement`.
+CSS text strings are not accepted by Base UI's style composition API.
+
+The optional temporal adapters require their matching peer packages:
+
+```sh
+npm install date-fns @date-fns/tz # Date-fns adapter
+npm install luxon               # Luxon adapter
+```
+
+TypeScript users of the Luxon adapter also need `@types/luxon`.
+
+## Development checks
+
+From the repository root:
+
+```sh
+pnpm --dir packages/base-ui test          # Native, differential and SSR tests
+pnpm --dir packages/base-ui test:upstream # Adapted upstream suite in jsdom
+pnpm --dir packages/base-ui test:browser  # Adapted upstream suite in Chromium
+pnpm --dir packages/base-ui test:pristine # Immutable React oracle in jsdom
+pnpm --dir packages/base-ui upstream:verify
+```
+
+## Migrating from the Base UI 1.6 binding
+
+Upgrade `octane` to **0.2.5 or later in the 0.2 line** together with this binding,
+`@octanejs/base-ui-utils`, `@octanejs/testing-library`, and `@octanejs/shadcn` when
+used. These packages require the compiler, hydration, and `act` support released
+in that coordinated patch. Earlier Octane 0.1 and 0.2 releases are not supported.
+
+- Select, Combobox, Autocomplete, Drawer, Navigation Menu, OTP Field, Scroll Area,
+  Toolbar, temporal adapters, and the remaining upstream parts are now available.
+- Existing primitives use the Base UI 1.8 implementations and public props. Keep
+  using component namespaces such as `Accordion.Root` and `Dialog.createHandle`.
+  Previously exported named components, handle constructors/factories, Toast
+  manager helpers, and Tabs type aliases remain available at the root and their
+  component entries. `useMediaQuery(query)` still works from the root or
+  `/unstable-use-media-query`; its options remain optional.
+- Packages publish authored Octane source. Use the Octane compiler integration
+  in your consumer toolchain; precompiled CommonJS export conditions are no
+  longer provided.
+- The export map now lists the upstream public entries explicitly. The previous
+  `/internal` and wildcard `/utils/*` implementation paths are unavailable.
+  Import supported utilities from `@octanejs/base-ui-utils`, for example
+  `@octanejs/base-ui-utils/usePreviousValue`, and composite primitives from
+  `@octanejs/base-ui/internals/composite`. Other private implementation paths
+  have no supported replacement contract.
 
 ## Intentional divergences from Base UI (React)
 
@@ -38,6 +93,8 @@ Every component takes Base UI's universal composition props — `render` (a JSX
 - **ref-as-prop.** No `forwardRef`; `ref` is a normal prop (React-19 shape).
 - **`className` composition** follows octane's `normalizeClass` at the apply site; the
   `render`-prop merge concatenates strings exactly like Base UI.
+- Octane does not replay mount effects in Strict Mode or implement React's
+  Server Components Flight format.
 
 ## Status
 

package/UPSTREAM.md

@@ -1,66 +1,166 @@
 # Base UI upstream ledger
 
-`@octanejs/base-ui` targets `@base-ui/react@1.6.0` from
-`https://github.com/mui/base-ui.git`.
-
-| Package | Version | Tag | Commit | npm SHA-256 |
-| --- | --- | --- | --- | --- |
-| `@base-ui/react` | `1.6.0` | `v1.6.0` | `b34551d644f2e58ebf8fc1050d949f6654ceca6c` | `583e60023a77fed45caf8a2f980813e8a75e2f2a97f59c30380d2234cc3e0423` |
-
-The lockfile integrity is
-`sha512-/jzjTWJYXhRFO45Bev9lc3cHbmjzCMpUqbMZ2AgKy/z25mY9B6shGSNcXcjQar9n5doM0KYW1W8fcFv2jZBuMw==`.
-The annotated tag is unsigned and peels to the commit above. The supported range is this exact
-release; upgrades require a new crosswalk.
-
-## Source and test boundary
-
-- Canonical package root: `packages/react`
-- Public surface: the non-internal component/utility subpaths in `packages/react/package.json`
-- Runtime/type tests: `packages/react/src/**/*.{test,spec}.{ts,tsx}`
-- Shared test/support root: `packages/react/test`
-- License: MIT; pinned root `LICENSE` SHA-256
-  `07fc1b39d69d14bc7d40482a628f47226258eb01265db68ae684944b916beb2a`
-- React oracle: the workspace-pinned React and React DOM versions used by `@base-ui/react`
-
-The byte-exact React-facing source, runtime/type suites, shared support files, package metadata,
-and MIT license are vendored under `upstream/`. All 1,129 vendored files verify offline against
-the upstream git blob shas recorded in `audit/upstream.lock.json`, and the pinned license is
-republished at the package root as `LICENSE.upstream`. To restore or extend the vendored
-tree, fetch the pinned files with
-`pnpm react-port:materialize run --package-dir packages/base-ui` (or re-vendor from an
-immutable checkout of tag `v1.6.0` and re-run the lock).
-
-`audit/upstream-crosswalk.json` records all 43 public component/utility subpaths and 348
-runtime, type, and support artifacts. It classifies 35 subpaths as
-`surface-present-unverified` and eight as explicit gaps: Autocomplete, Combobox, Drawer,
-Navigation Menu, OTP Field, Scroll Area, Select, and Toolbar. Surface presence is not a
-behavioral parity claim.
-
-The canonical package has 273 runtime test files, 35 type-test files, and 40 support
-artifacts. Ten upstream Accordion, Collapsible, and Tabs files have selected cases adapted locally; the
-remaining suite is vendored but not adapted in full, so the binding remains
-`recorded-unverified`. The published npm package contains no canonical test files; that
-registry boundary is not evidence that the repository suite is absent.
-
-## Executable evidence
-
-The differential lane runs all 98 authored same-fixture scenarios against both Octane and the
-pinned `@base-ui/react` package and verifies their exact inventory. A separate adapted lane runs
-the 49 currently collected Accordion, Collapsible, and Tabs cases (selected transcriptions from
-the pin, not the full 273-file upstream runtime suite) and verifies that inventory. Focused lanes
-bind representative cases to structured divergences. Local crosswalk/gap contract tests run in the
-ordinary `base-ui` Vitest project and are not react-parity evidence. Pristine upstream runtime,
-pristine type, and one-for-one adapted type lanes are still required before this binding can leave
-`recorded-unverified`.
-
-## Intentional divergences and known gaps
-
-- Host handlers use native DOM events rather than React's synthetic event layer.
-- React `forwardRef` wrappers become ref-as-prop; class values use Octane composition rules.
-- Base UI's internal standalone `useHover` combiner is not republished because no ported Base
-  UI component consumes it.
-- The shared default Tooltip delay-group refs match the pinned upstream behavior.
-- `NumberField.ScrubArea` and press-and-hold stepping remain gaps; steppers handle single
-  presses only.
-
-Structured divergence records and their executing cases live in `audit/react-parity.json`.
+`@octanejs/base-ui` targets `@base-ui/react@1.8.0`.
+
+- Repository: https://github.com/mui/base-ui
+- Immutable commit: `47b40521eab921c2756bf9bdb0b0f07fbfdb8c8c` (`v1.8.0`)
+- Source directory: `packages/react`
+- npm integrity: `sha512-P0/1sxo6SBVZOklKMIedvTWqw2s2IQzi9x5bIVsXu980cuSOD4NeuRSs+/L7LZQfDkZP/uRZyGPyfFl/B1oH+Q==`
+- License: MIT; the exact upstream text is published as `LICENSE.upstream`.
+
+## Source boundary
+
+The byte-exact source, tests, and package metadata live under `upstream/`.
+`audit/upstream.lock.json` pins each file by its git blob and SHA-256 digest.
+The npm provenance attestation was verified against the package integrity and
+this source commit because the registry metadata omits `gitHead`.
+
+## Verification
+
+The source boundary contains 315 runtime test files and 41 type-test files.
+The pristine runtime uses React 19.2.8. The upstream `typescript` command resolves
+TypeScript 7.0.2 through its `@typescript/native` alias; its separate TypeScript 6
+package only provides `tsc6`. Pristine and adapted type suites use separate programs.
+
+Both runtime runners preserve the pinned `vitest.shared.mts` policy: one retry
+in CI and none otherwise. The byte-exact configuration is retained under
+`audit/repository-fixtures/`. Test identities, assertions, skips, and todos remain
+subject to the same strict report validation after retries.
+
+Native source and adapted type tests pass strict `tsrx-tsc` checks with declaration
+checking enabled. The formal public type gate also passes. All 79 Base UI public entries and 2,073 entry/export pairs have consumer assertions, including 31 retained Octane compatibility exports.
+The gate verifies the npm tarball integrity and installed declaration bytes before
+using them as witnesses for intentional opaque types. New erasure in callbacks,
+generic arguments, inherited properties, and refs is rejected. See
+`tests/types/public.tsx` and `tests/types/published-contract.ts`.
+
+The full workspace pack check passes with the current public type and export-map
+changes: 124 tarballs, 1,174 raw TSRX files, and 51 strict installed binding
+consumers, each checked with and without Node ambient types.
+
+The registration crosswalk accounts for all 9,342 immutable source registrations:
+9,326 retained conformance registrations and 16 explicit React-only exclusions.
+These are source registrations, including type assertions and helper expansions;
+they are distinct from executed test counts. Regenerate it with
+`node packages/base-ui/scripts/build-registration-crosswalk.mjs --source-checkout <Base-UI-git-checkout>`.
+
+The complete pristine and adapted runtime, Chromium, and type lanes pass.
+Chromium executes 8,726 pristine and 8,709 native tests; unit execution passes
+7,775 pristine and 7,758 native tests. All 98 same-fixture differential cases pass.
+The reports account separately for every declared skip and todo. Native SSR,
+hydration, focus, keyboard, portal, and identity regressions also pass.
+
+## Native adaptations
+
+- Host callbacks receive native DOM events; text edits use `onInput`.
+- Refs are ordinary props, including callback cleanup and composed refs.
+- Octane does not replay mount effects or render functions in Strict Mode.
+- React Server Components and the private Flight format are unsupported.
+- Object styles are preserved through Base UI composition; CSS text is rejected.
+- The compiler assigns native hook slots to components and shared helpers.
+
+The authored components use standard TypeScript/JSX syntax within `.tsrx` files.
+Their formatter uses Prettier's TypeScript parser, which preserves generic call
+signatures and mixed logical/nullish expressions. The TSRX formatter currently
+loses required parentheses in these forms. This is a parser selection, and all
+authored files remain subject to the repository format check.
+
+Both runtime test lanes use upstream's exact jsdom 27.4.0. The shared environment
+resolves Vitest from the binding so invoking tests from the repository root does
+not silently substitute the root workspace's newer jsdom peer. The pristine test
+helper also resolves the pinned user-event 14.6.3 instead of a newer transitive
+version. The complete pristine run passes 7,775 Base UI and 146 utility tests;
+upstream skip and todo registrations remain visible in its report.
+
+The upstream Luxon source carries an existing `@ts-nocheck` directive. Its npm
+declarations also have errors when compiled together with the Date-fns adapter
+augmentation. The binding preserves this upstream limitation; generated consumer
+contracts derive literal property and arity expectations from verified npm types
+without importing conflicting upstream adapter programs into the native consumer.
+
+Runtime comparisons for changed menu defaults, Strict Mode callback counts, and
+abandoned derived state live in `packages/base-ui/tests/react-controls/`.
+
+## Export surface
+
+| Entry | Authored source |
+| --- | --- |
+| `.` | `./src/index.ts` |
+| `./accordion` | `./src/accordion/index.ts` |
+| `./alert-dialog` | `./src/alert-dialog/index.ts` |
+| `./autocomplete` | `./src/autocomplete/index.ts` |
+| `./avatar` | `./src/avatar/index.ts` |
+| `./button` | `./src/button/index.ts` |
+| `./checkbox` | `./src/checkbox/index.ts` |
+| `./checkbox-group` | `./src/checkbox-group/index.ts` |
+| `./collapsible` | `./src/collapsible/index.ts` |
+| `./combobox` | `./src/combobox/index.ts` |
+| `./csp-provider` | `./src/csp-provider/index.ts` |
+| `./context-menu` | `./src/context-menu/index.ts` |
+| `./dialog` | `./src/dialog/index.ts` |
+| `./direction-provider` | `./src/direction-provider/index.ts` |
+| `./drawer` | `./src/drawer/index.ts` |
+| `./field` | `./src/field/index.ts` |
+| `./fieldset` | `./src/fieldset/index.ts` |
+| `./form` | `./src/form/index.ts` |
+| `./input` | `./src/input/index.ts` |
+| `./menu` | `./src/menu/index.ts` |
+| `./menubar` | `./src/menubar/index.ts` |
+| `./merge-props` | `./src/merge-props/index.ts` |
+| `./meter` | `./src/meter/index.ts` |
+| `./navigation-menu` | `./src/navigation-menu/index.ts` |
+| `./number-field` | `./src/number-field/index.ts` |
+| `./otp-field` | `./src/otp-field/index.ts` |
+| `./popover` | `./src/popover/index.ts` |
+| `./preview-card` | `./src/preview-card/index.ts` |
+| `./progress` | `./src/progress/index.ts` |
+| `./radio` | `./src/radio/index.ts` |
+| `./radio-group` | `./src/radio-group/index.ts` |
+| `./scroll-area` | `./src/scroll-area/index.ts` |
+| `./select` | `./src/select/index.ts` |
+| `./separator` | `./src/separator/index.ts` |
+| `./slider` | `./src/slider/index.ts` |
+| `./switch` | `./src/switch/index.ts` |
+| `./tabs` | `./src/tabs/index.ts` |
+| `./toast` | `./src/toast/index.ts` |
+| `./toggle` | `./src/toggle/index.ts` |
+| `./toggle-group` | `./src/toggle-group/index.ts` |
+| `./toolbar` | `./src/toolbar/index.ts` |
+| `./tooltip` | `./src/tooltip/index.ts` |
+| `./types` | `./src/types/index.ts` |
+| `./unstable-use-media-query` | `./src/unstable-use-media-query/index.ts` |
+| `./use-render` | `./src/use-render/index.ts` |
+| `./internals/composite` | `./src/internals/composite/index.ts` |
+| `./internals/constants` | `./src/internals/constants.ts` |
+| `./internals/createBaseUIEventDetails` | `./src/internals/createBaseUIEventDetails.ts` |
+| `./internals/csp-context` | `./src/internals/csp-context/index.ts` |
+| `./internals/direction-context` | `./src/internals/direction-context/index.ts` |
+| `./internals/field-constants` | `./src/internals/field-constants/index.ts` |
+| `./internals/field-register-control` | `./src/internals/field-register-control/index.ts` |
+| `./internals/field-root-context` | `./src/internals/field-root-context/index.ts` |
+| `./internals/filter` | `./src/internals/filter.ts` |
+| `./internals/itemEquality` | `./src/internals/itemEquality.ts` |
+| `./internals/form-context` | `./src/internals/form-context/index.ts` |
+| `./internals/getDisabledMountTransitionStyles` | `./src/internals/getDisabledMountTransitionStyles.ts` |
+| `./internals/getStateAttributesProps` | `./src/internals/getStateAttributesProps.ts` |
+| `./internals/labelable-provider` | `./src/internals/labelable-provider/index.ts` |
+| `./internals/noop` | `./src/internals/noop.ts` |
+| `./internals/reasons` | `./src/internals/reasons.ts` |
+| `./internals/resolveValueLabel` | `./src/internals/resolveValueLabel.tsrx` |
+| `./internals/RequestQueue` | `./src/internals/RequestQueue.ts` |
+| `./internals/serializeValue` | `./src/internals/serializeValue.ts` |
+| `./internals/stateAttributesMapping` | `./src/internals/stateAttributesMapping.ts` |
+| `./internals/temporal` | `./src/internals/temporal/index.ts` |
+| `./internals/temporal-adapter-date-fns` | `./src/internals/temporal-adapter-date-fns/index.ts` |
+| `./internals/temporal-adapter-luxon` | `./src/internals/temporal-adapter-luxon/index.ts` |
+| `./internals/TimeoutManager` | `./src/internals/TimeoutManager.ts` |
+| `./internals/types` | `./src/internals/types.ts` |
+| `./internals/use-button` | `./src/internals/use-button/index.ts` |
+| `./internals/useBaseUiId` | `./src/internals/useBaseUiId.ts` |
+| `./internals/useAnchorPositioning` | `./src/internals/useAnchorPositioning.ts` |
+| `./internals/useAnimationsFinished` | `./src/internals/useAnimationsFinished.ts` |
+| `./internals/useOpenChangeComplete` | `./src/internals/useOpenChangeComplete.tsrx` |
+| `./internals/usePressAndHold` | `./src/internals/usePressAndHold.ts` |
+| `./internals/useRenderElement` | `./src/internals/useRenderElement.tsrx` |
+| `./internals/useValueChanged` | `./src/internals/useValueChanged.ts` |
+| `./internals/useTransitionStatus` | `./src/internals/useTransitionStatus.ts` |