4.4.2

Apr 29, 2026 · 9 packages · 29 unique changes · 15 release entries

bundleslibsmodulesBreaking changes

Release summaries

adaptive-object-reference-panel
Promote object-reference detail panels to a reusable adaptive sheet/drawer surface.
maintainer
Design-system now exposes AdaptivePanel as the shared responsive sheet/drawer primitive and wires object-reference details through it.
integrator
ObjectReferenceHandler supports same-page vs new-page detail opening, rich nested properties, and configurable sheet/drawer behavior with responsive defaults.
customer
Reference interactions can show richer details in a desktop sheet or mobile drawer without custom per-screen logic.
adaptive-panel-menu-migration
Route design-system mobile menu overlays through the shared AdaptivePanel primitive.
maintainer
Header and marketing header mobile menus now use AdaptivePanel instead of direct sheet composition, leaving sheet/drawer primitives behind the shared overlay adapter.
integrator
Design-system overlay behavior is more consistent because mobile menu panels and object references share the AdaptivePanel boundary.
customer
Mobile menus keep the same behavior while using the shared responsive panel implementation.
application-shell-navigation
Add design-system application shell primitives with typed navigation, command search, breadcrumbs, native bottom-tab adaptation, and PageOutline support.
maintainer
Design-system maintainers now have a focused shell API for application frames, navigation sections, breadcrumbs, commands, and page outlines.
integrator
Web and Expo app developers can adopt AppShell and PageOutline from the shell subpath while existing AppLayout, AppSidebar, AppHeader, NavLink, and NavSection imports remain supported.
customer
Documentation readers get public library docs with copy-ready AI prompts for fresh application shell implementation and existing-app refactors.
appshell-notification-layout
Fix AppShell desktop sidebar collapse/layout and web notification dismissal behavior.
integrator
AppShell now keeps the desktop topbar inset beside the sidebar, exposes a shared sidebar collapse trigger, and dismisses the web notification panel on outside click, Escape, or trigger toggle.
data-table-ux-stability-upgrade
Harden the shared data-table stack and add a first-class composed toolbar for search, filter chips, selection summary, and hidden-column recovery.
maintainer
The shared table controller now sanitizes stale row and column state, and the design-system exports `DataTableToolbar` as the preferred composed UX layer above the primitive tables.
integrator
Integrators can adopt `DataTableToolbar` without changing the underlying `DataTable` or `useContractTable` API, and server-paginated tables now behave more defensively when data, columns, or totals change.
customer
The CRM and canonical data-grid examples now expose search, filter chips, selection summaries, safer column recovery, and less failure-prone table interactions across web and native paths.
design-system-core-hardening
Add focused design-system subpaths and harden ThemeSpec runtime, Tailwind bridge, form-control helpers, and form renderer internals without changing root-import compatibility.
maintainer
Maintainers now have smaller internal design-system modules and focused subpaths for theme, controls, forms, layout, and renderers.
integrator
Integrators can keep root imports or adopt focused subpaths such as `@contractspec/lib.design-system/theme` and `@contractspec/lib.design-system/forms`.
customer
Contract-rendered forms and themed controls keep the same behavior while the design-system internals become easier to maintain.
design-system-select-groups
Add grouped option support to design-system Select controls across web and native.
maintainer
The design-system Select wrappers now share grouped-option normalization and expose a typed grouped Select API.
integrator
Existing flat Select options keep working, while callers can opt into translated grouped option sections on web and native.
customer
Select controls can now present options in labelled groups consistently across web and native surfaces.
design-system-themed-controls
Add a ThemeSpec-aware and TranslationSpec-aware design-system form/control layer with stack primitives, exported control wrappers, and FormSpec renderer alignment.
maintainer
Maintainers now have a shared design-system control boundary for forms, stacks, themes, translations, and FormSpec rendering.
integrator
Integrators can import themed and translated controls from `@contractspec/lib.design-system` instead of reaching into web or native UI kit primitives directly.
customer
Product surfaces and contract-rendered forms can now share the same ThemeSpec-aware and TranslationSpec-aware design-system controls across web and React Native.
forms-option-surface-aliases
Add ThemeSpec Tailwind aliases for FormSpec option surface backgrounds.
maintainer
The ThemeSpec Tailwind bridge now emits shadcn-compatible color aliases for popover, card, and input surfaces.
integrator
Apps using generated design-system theme CSS get the color aliases expected by Radix/shadcn select and combobox primitives.
customer
Contract-rendered select and combobox option panels keep a proper themed surface instead of falling back to transparency when the app relies on ThemeSpec CSS.
forms-password-visibility-toggle
Fix FormSpec password visibility toggles so rendered password fields can reveal and re-mask values.
maintainer
The web password primitive now keeps its computed `type` authoritative over upstream input props from FormSpec renderers.
integrator
Design-system FormSpec renderers can pass legacy `type: "password"` hints without disabling the visibility toggle.
customer
Contract-driven password fields now reveal the password when the visibility toggle changes from closed eye to open eye.
forms-phone-ux-regression
Fix FormSpec phone country-select rendering to remove duplicated country adornments.
customer
Split FormSpec phone fields now show one clear country selector instead of duplicating the flag and calling code beside the select.
integrator
Design-system phone country options now honor the configured flag/calling-code display parts, while the selected country control owns those adornments in select mode.
native-design-system-platform-suffix
Migrate design-system platform implementation suffixes from `.mobile` to `.native`.
integrator
Design-system platform variants now use Metro's standard `.native` suffix and no longer publish `.mobile` subpaths.
maintainer
Package exports, registry metadata, and cross-platform UI docs now describe `.tsx` / `.native.tsx` renderer pairs.
notion-page-outline
Improve PageOutline desktop behavior with a Notion-like floating rail that keeps AppShell content centered while expanding on hover or keyboard focus.
integrator
AppShell consumers get a floating desktop PageOutline that no longer reserves a right content column, while mobile and native outline behavior remains menu-contained.
maintainer
Design-system maintainers can opt PageOutline into a floating variant while preserving existing rail and compact variants.
object-reference-handler
Add an extensible design-system object reference handler for actionable references.
maintainer
The design-system package now exposes a public object-reference component group with schema-friendly descriptors, runtime action handlers, and paired web/native implementations.
integrator
Product surfaces can replace inert addresses, phone numbers, users, customers, files, URLs, and custom references with one extensible interaction surface.
customer
Reference text can now offer quick actions such as copy, open, call, or maps navigation from a consistent interaction surface.
unified-design-system-tabs
Add a unified design-system Tabs primitive and migrate local tab consumers away from ui-kit leaf imports.
maintainer
Maintainers can expose tabbed product surfaces through the design-system root instead of choosing between web and native UI-kit tab APIs.
integrator
Integrators can use one `Tabs` API with optional `value`, `defaultValue`, and `onValueChange` props across web and native surfaces.
customer
Example dashboards and execution consoles keep their existing tabbed UX while using the cross-platform design-system primitive.

Deprecations

- Direct imports such as `@contractspec/lib.design-system/components/molecules/Tabs.mobile` have been replaced by `.native` subpaths.

Migration guide

Adopt the focused application shell subpath
Existing shell-related imports keep working, but new application frames should use the focused shell entrypoint.
When: When creating a new app shell or refactoring an existing navigation frame.
1. Import AppShell and PageOutline from "@contractspec/lib.design-system/shell".
2. Keep existing AppLayout, AppSidebar, AppHeader, NavLink, and NavSection imports where no refactor is needed.
3. Use the public library docs prompts when migrating existing app frame structure.
Move high-level table UX into `DataTableToolbar`
Keep the primitive `DataTable` lean and compose richer UX through the existing `toolbar` slot.
When: When a table needs search, active chips, selection summary, or hidden-column recovery.
1. Import `DataTableToolbar` from `@contractspec/lib.design-system`.
2. Pass the existing table controller into `DataTableToolbar`.
3. Keep product-specific buttons or filter toggles in `actionsStart` or `actionsEnd`.
Reset page-level UI state when server filters change
The examples now reset page index when search or status filters change so server-mode tables stay aligned with remote pagination.
When: When composing server-paginated tables with external search or filter state.
1. Reset `pageIndex` whenever remote search or filter inputs change.
2. Continue passing sorting and pagination through the shared controller state.
Replace direct `.mobile` design-system imports
Required
Move direct design-system platform imports from `.mobile` to `.native`.
1. Replace imports ending in `.mobile` with the matching `.native` subpath.
2. Prefer unsuffixed design-system imports when the same call site should run on both web and native.
3. Restart Metro after upgrading so stale package export maps are cleared.
Prefer design-system Tabs for shared product surfaces
Consumers should import tabs from `@contractspec/lib.design-system` instead of lower-level UI-kit tab modules.
When: When building or updating tabbed React or React Native UI.
1. Replace `@contractspec/lib.ui-kit-web/ui/tabs` or `@contractspec/lib.ui-kit/ui/tabs` imports with `@contractspec/lib.design-system`.
2. Use `defaultValue` for uncontrolled tabs, or `value` plus `onValueChange` for controlled tabs.
3. Keep existing `TabsList`, `TabsTrigger`, and `TabsContent` structure.

Upgrade steps

Reuse AdaptivePanel for responsive overlay choices
assisted
Replace one-off sheet/drawer branching with AdaptivePanel when a surface should use sheets on desktop and drawers on mobile.
Packages: @contractspec/lib.design-system
1. Import `AdaptivePanel` from `@contractspec/lib.design-system`.
2. Use the default responsive mode, or force `mode="sheet"` / `mode="drawer"` when product requirements need one presentation.
Use AppShell and PageOutline for new application frames
assisted
New application shells should compose the focused shell primitives instead of rebuilding frame, navigation, breadcrumb, command, and outline behavior locally.
Packages: @contractspec/lib.design-system, @contractspec/bundle.library, @contractspec/bundle.marketing
1. Import AppShell and PageOutline from "@contractspec/lib.design-system/shell".
2. Keep legacy imports for existing AppLayout, AppSidebar, AppHeader, NavLink, and NavSection consumers.
3. Re-run design-system and affected docs or app typechecks after adopting the shell subpath.
Re-run focused table verification after upgrading
assisted
The web, native, design-system, and example surfaces should be validated together because the UX and stability changes span all four layers.
Packages: @contractspec/lib.design-system, @contractspec/lib.presentation-runtime-react, @contractspec/lib.ui-kit-web, @contractspec/lib.ui-kit, @contractspec/example.crm-pipeline, @contractspec/example.data-grid-showcase
1. Run the focused table test suites in `presentation-runtime-react`, `ui-kit-web`, `ui-kit`, `design-system`, `example.crm-pipeline`, and `example.data-grid-showcase`.
2. Re-run package typechecks and lint checks for the touched libraries and examples.
3. Spot-check server-paginated and client-side examples to confirm search, chips, loading, empty states, and column recovery behave as expected.
Prefer focused subpaths for new imports
assisted
Existing root imports stay supported, but new code can import from focused design-system surfaces.
Packages: @contractspec/lib.design-system
1. Use `@contractspec/lib.design-system/theme` for ThemeSpec runtime and Tailwind helpers.
2. Use `@contractspec/lib.design-system/controls` for themed and translated controls.
3. Use `@contractspec/lib.design-system/forms` for form layouts, controls, and `ZodForm`.
4. Use `@contractspec/lib.design-system/layout` for stack primitives.
Prefer design-system controls for themed and translated forms
manual
Use the design-system form and stack exports before dropping to platform-specific UI kit primitives.
Packages: @contractspec/lib.design-system
1. Wrap surfaces in `DesignSystemThemeProvider` when ThemeSpec or scoped theme overrides are available.
2. Wrap surfaces in `DesignSystemTranslationProvider` when TranslationSpec messages should resolve labels or placeholders.
3. Import controls such as `Select`, `Autocomplete`, `DatePicker`, `TimePicker`, `DateTimePicker`, `Box`, `HStack`, and `VStack` from `@contractspec/lib.design-system`.
Regenerate design-system exports
manual
Keep package exports and registry metadata aligned with `.native` source files.
Packages: @contractspec/lib.design-system, @contractspec/lib.presentation-runtime-core, @contractspec/bundle.library
1. Run `cd packages/libs/design-system && bun run prebuild && bun run registry:build`.
2. Verify no `*.mobile.tsx` platform files remain in `packages/libs/design-system/src`.
Use the floating PageOutline variant for wide desktop shells
assisted
AppShell now uses the floating outline automatically; direct PageOutline consumers can opt in with `variant="floating"`.
Packages: @contractspec/lib.design-system
1. Use `variant="floating"` for direct web PageOutline usage that should reduce when inactive.
2. Keep `variant="rail"` or `variant="compact"` where a static inline outline is still preferred.
Migrate direct tab imports
manual
Move tabbed product surfaces to the design-system root export.
Packages: @contractspec/lib.design-system, @contractspec/example.agent-console, @contractspec/example.crm-pipeline, @contractspec/example.data-grid-showcase, @contractspec/module.builder-workbench, @contractspec/module.execution-console
1. Import `Tabs`, `TabsList`, `TabsTrigger`, and `TabsContent` from `@contractspec/lib.design-system`.
2. Add `@contractspec/lib.design-system` as a package dependency if the consumer package did not already depend on it.
3. Re-run typecheck for the migrated package.

Unique release changes

- Harden the shared data-table stack and add a first-class composed toolbar for search, filter chips, selection summary, and hidden-column recovery.
4 packages · 4 occurrences
- Keep the primitive `DataTable` lean and compose richer UX through the existing `toolbar` slot.
4 packages · 4 occurrences
- The examples now reset page index when search or status filters change so server-mode tables stay aligned with remote pagination.
4 packages · 4 occurrences
- The web, native, design-system, and example surfaces should be validated together because the UX and stability changes span all four layers.
4 packages · 4 occurrences
- Add a unified design-system Tabs primitive and migrate local tab consumers away from ui-kit leaf imports.
3 packages · 3 occurrences
- Add design-system application shell primitives with typed navigation, command search, breadcrumbs, native bottom-tab adaptation, and PageOutline support.
3 packages · 3 occurrences
- Consumers should import tabs from `@contractspec/lib.design-system` instead of lower-level UI-kit tab modules.
3 packages · 3 occurrences
- Direct imports such as `@contractspec/lib.design-system/components/molecules/Tabs.mobile` have been replaced by `.native` subpaths.
3 packages · 3 occurrences
- Existing shell-related imports keep working, but new application frames should use the focused shell entrypoint.
3 packages · 3 occurrences
- Keep package exports and registry metadata aligned with `.native` source files.
3 packages · 3 occurrences
- Migrate design-system platform implementation suffixes from `.mobile` to `.native`.
3 packages · 3 occurrences
- Move direct design-system platform imports from `.mobile` to `.native`.
3 packages · 3 occurrences
- Move tabbed product surfaces to the design-system root export.
3 packages · 3 occurrences
- New application shells should compose the focused shell primitives instead of rebuilding frame, navigation, breadcrumb, command, and outline behavior locally.
3 packages · 3 occurrences
- Fix FormSpec password visibility toggles so rendered password fields can reveal and re-mask values.
2 packages · 2 occurrences
- Add a ThemeSpec-aware and TranslationSpec-aware design-system form/control layer with stack primitives, exported control wrappers, and FormSpec renderer alignment.
1 packages · 1 occurrences
- Add an extensible design-system object reference handler for actionable references.
1 packages · 1 occurrences
- Add focused design-system subpaths and harden ThemeSpec runtime, Tailwind bridge, form-control helpers, and form renderer internals without changing root-import compatibility.
1 packages · 1 occurrences
- Add grouped option support to design-system Select controls across web and native.
1 packages · 1 occurrences
- Add ThemeSpec Tailwind aliases for FormSpec option surface backgrounds.
1 packages · 1 occurrences
- AppShell now uses the floating outline automatically; direct PageOutline consumers can opt in with `variant="floating"`.
1 packages · 1 occurrences
- Existing root imports stay supported, but new code can import from focused design-system surfaces.
1 packages · 1 occurrences
- Fix AppShell desktop sidebar collapse/layout and web notification dismissal behavior.
1 packages · 1 occurrences
- Fix FormSpec phone country-select rendering to remove duplicated country adornments.
1 packages · 1 occurrences
- Improve PageOutline desktop behavior with a Notion-like floating rail that keeps AppShell content centered while expanding on hover or keyboard focus.
1 packages · 1 occurrences
- Promote object-reference detail panels to a reusable adaptive sheet/drawer surface.
1 packages · 1 occurrences
- Replace one-off sheet/drawer branching with AdaptivePanel when a surface should use sheets on desktop and drawers on mobile.
1 packages · 1 occurrences
- Route design-system mobile menu overlays through the shared AdaptivePanel primitive.
1 packages · 1 occurrences
- Use the design-system form and stack exports before dropping to platform-specific UI kit primitives.
1 packages · 1 occurrences

Impacted packages

@contractspec/bundle.library
Layer: bundles · 4 changes
@contractspec/bundle.marketing
Layer: bundles · 3 changes
@contractspec/lib.design-system
Layer: libs · 3 changes
@contractspec/lib.presentation-runtime-core
Layer: libs · 4 changes
@contractspec/lib.presentation-runtime-react
Layer: libs · 4 changes
@contractspec/lib.ui-kit
Layer: libs · 4 changes
@contractspec/lib.ui-kit-web
Layer: libs · 1 changes
@contractspec/module.builder-workbench
Layer: modules · 3 changes
@contractspec/module.execution-console
Layer: modules · 3 changes