[6.x] Legacy bridge

CHANGELOG.md

@@ -5,10 +5,39 @@
 > [!IMPORTANT]
 > This update contains breaking changes for plugins. See [#19882](https://github.com/craftcms/cms/pull/19882) for details.
 
+- Control panel screens from plugins that haven’t been updated for Craft 6 now render inside the control panel shell, with their tabs, assets, and JavaScript intact.
+- Element index screens from plugins that haven’t been updated for Craft 6 now use the new element index, with the element type’s sources in the secondary nav and a Customize Sources action.
+- Element sources’ `status` and `badgeCount` values are now shown in the secondary nav, as they were in the Craft 5 sidebar. ([#19892](https://github.com/craftcms/cms/pull/19892))
+- Tabs now mirror the selected tab in the URL hash, select the tab named by the hash on page load, and keep it after saving.
+- Selectize fields are now rendered as `<craft-combobox>` web components, rather than Selectize instances.
+- Autosuggest inputs are now rendered as `<craft-combobox>` web components, rather than Vue 2 `vue-autosuggest` instances.
+- Autosuggest inputs now match suggestions on their hint as well as their label, and no longer cap each suggestion group at five items.
+- Added `CraftCms\Cms\Cp\Navigation::sourceSubnav()`, which builds a subnav from an element type’s sources, for plugins adding their own control panel section.
+- Added `CraftCms\Cms\Cp\Data\ActionItem::$status` and `status()`. ([#19892](https://github.com/craftcms/cms/pull/19892))
+- Added `craft.cp.selectize()` and `CraftCms\Cms\Cp\FormFields::selectizeFromConfig()`, which render the legacy selectize variables as a combobox.
+- Added `craft.cp.select()` and `CraftCms\Cms\Cp\FormFields::selectFromConfig()`, which render the legacy select variables as a `<craft-select>`.
+- Added `craft.cp.autosuggest()` and `CraftCms\Cms\Cp\FormFields::autosuggestFromConfig()`, which render the legacy autosuggest variables as a combobox. Craft 5’s `suggestions` shape is still accepted.
+- Added `CraftCms\Cms\Cp\Components\Combobox::labelledBy()`, for a combobox labelled by an element the caller renders itself.
+- Added `CraftCms\Cms\Plugin\Concerns\HasSettings::createSettings()`, a static method which replaces `CraftCms\Cms\Contracts\PluginInterface::createSettings()`. ([#19574](https://github.com/craftcms/cms/pull/19574))
+- `CraftCms\Cms\Element\Element::searchableAttributes()` is now `final`. `defineSearchableAttributes()` should be overridden instead, including by element types extending `craft\base\Element` through the Yii adapter.
+- `CraftCms\Cms\Element\Element::prepareEditScreen()` now accepts a `Symfony\Component\HttpFoundation\Response|CraftCms\Cms\Http\Responses\CpScreenResponse` argument, rather than `yii\web\Response`. Overrides must update their signatures.
+- `CraftCms\Cms\Element\Queries\ElementQuery::statusCondition()` now returns a `Closure` which modifies an `Illuminate\Database\Query\Builder`, rather than a Yii query condition. Overrides must update their signatures and return closures.
+- `craft\base\Model::attributes()` now declares an `array` return type. Overrides must update their signatures.
+- Plugin settings models must now extend `CraftCms\Cms\Plugin\PluginSettings` rather than `craft\base\Model`.
+- Plugin settings are now validated using Laravel validation rules returned by `CraftCms\Cms\Plugin\PluginSettings::getRules()`, rather than Yii validation rules returned by `rules()`. Validation errors are added via the `$fail` callback or `errors()`, rather than `addError()`.
+- Plugin settings are now persisted based on the settings model’s public properties, via `CraftCms\Cms\Plugin\PluginSettings::configData()`. Settings stored in private properties with getter and setter methods must be redeclared as public properties, or included by overriding `configData()`.
+- Removed the `data` and `methods` blocks from the `_includes/forms/autosuggest.twig` template, along with the Vue instance they configured. Templates that overrode them should pass `suggestions` instead.
+- Removed `CraftCms\Cms\Plugin\Contracts\PluginInterface::createSettingsModel()`. The static `createSettings()` must be implemented instead. (`createSettingsModel()` remains supported for plugins extending `craft\base\Plugin` through the Yii adapter.) ([#19574](https://github.com/craftcms/cms/pull/19574))
 - Improved control panel styling for medium-sized viewports.
 - Renamed `CraftCms\Cms\Form` to `CraftCms\Cms\Ui`, along with its `Form` classes and methods, and the JavaScript `forms` module and its definition APIs to `ui`, including payload fields and refresh endpoints. ([#19882](https://github.com/craftcms/cms/pull/19882))
 - Fixed an error that could occur after upgrading to Craft 6 when Laravel queue or other supporting database tables were missing. ([#19889](https://github.com/craftcms/cms/pull/19889))
 - Fixed a bug where new control panel assets weren’t getting published when updating via the control panel or `craft:update` command.
+- Fixed an error that occurred when a Craft 5 plugin registered a utility, which no longer satisfied `CraftCms\Cms\Utility\UtilityTypes`’ contract. ([#19852](https://github.com/craftcms/cms/pull/19852))
+- Fixed an error that occurred when registering asset bundles that depend on `CraftCms\Cms\View\LegacyAssets\HtmxAsset`. The bundle is now deprecated and does nothing.
+- Fixed a bug where the tab strip wasn’t guttered with the content it sits above. ([#19861](https://github.com/craftcms/cms/pull/19861))
+- Fixed a bug where an editable table that wasn’t visible when the page loaded didn’t initialize until the window was resized.
+- Fixed a bug where environment variable, alias, and template suggestions weren’t sorted alphabetically.
+- Fixed a bug where status indicators for disabled elements were filled in rather than outlined, and custom status colors were shown as gray. ([#19892](https://github.com/craftcms/cms/pull/19892))
 - Fixed a bug where admin tables no longer had selectable rows. ([#19893](https://github.com/craftcms/cms/pull/19893))
 - Fixed a bug where the license enforcement screen wasn’t showing the “Continue to the control panel” link after the countdown ended. ([#19895](https://github.com/craftcms/cms/issues/19895))
 

packages/craftcms-legacy/cp/src/js/BaseElementIndex.js

@@ -3928,7 +3928,11 @@ Craft.BaseElementIndex = Garnish.Base.extend(
         })
         .appendTo($form);
 
-      const $exportSubmit = new Garnish.MultiFunctionBtn($submitBtn);
+      // Guarded: the modernized Garnish has no MultiFunctionBtn. Without it
+      // the export button just stays a plain button rather than throwing.
+      const $exportSubmit = Garnish.MultiFunctionBtn
+        ? new Garnish.MultiFunctionBtn($submitBtn)
+        : null;
 
       var hud = new Garnish.HUD(this.$exportBtn, $form);
 
@@ -3946,7 +3950,7 @@ Craft.BaseElementIndex = Garnish.Base.extend(
         }
 
         submitting = true;
-        $exportSubmit.busyEvent();
+        $exportSubmit?.busyEvent();
 
         var params = this.getViewParams();
         delete params.baseCriteria.offset;
@@ -3986,7 +3990,7 @@ Craft.BaseElementIndex = Garnish.Base.extend(
           })
           .finally(() => {
             submitting = false;
-            $exportSubmit.successEvent();
+            $exportSubmit?.successEvent();
           });
       });
     },

packages/craftcms-legacy/cp/src/js/Craft.js

@@ -3041,7 +3041,7 @@ $.extend($.fn, {
    */
   checkboxselect: function () {
     return this.each(function () {
-      if (!$.data(this, 'checkboxSelect')) {
+      if (!$.data(this, 'checkboxSelect') && Garnish.CheckboxSelect) {
         new Garnish.CheckboxSelect(this, {
           storageKey: this.getAttribute('data-storage-key'),
         });
@@ -3062,7 +3062,7 @@ $.extend($.fn, {
 
   nicetext: function () {
     return this.each(function () {
-      if (!$.data(this, 'nicetext')) {
+      if (!$.data(this, 'nicetext') && Garnish.NiceText) {
         new Garnish.NiceText(this);
       }
     });
@@ -3277,16 +3277,22 @@ $.extend($.fn, {
   },
 });
 
-// Override Garnish.NiceText.charsLeftHtml() to be more accessible
-Garnish.NiceText.charsLeftHtml = (charsLeft) => {
-  return Craft.t(
-    'app',
-    '<span class="visually-hidden">Characters left:</span> {chars, number}',
-    {
-      chars: charsLeft,
-    }
-  );
-};
+// Override Garnish.NiceText.charsLeftHtml() to be more accessible.
+// Guarded: the modernized Garnish has no NiceText — `craft-input`'s
+// `showCharsLeft` covers it — and this runs at module scope, so an
+// unguarded assignment aborts the rest of Craft.js on any page where the
+// modern namespace owns `window.Garnish`.
+if (Garnish.NiceText) {
+  Garnish.NiceText.charsLeftHtml = (charsLeft) => {
+    return Craft.t(
+      'app',
+      '<span class="visually-hidden">Characters left:</span> {chars, number}',
+      {
+        chars: charsLeft,
+      }
+    );
+  };
+}
 
 Garnish.$doc.ready(function () {
   Craft.initUiElements();

packages/craftcms-legacy/cp/src/js/UI.js

@@ -125,7 +125,9 @@ Craft.ui = {
       )
     );
 
-    if (config.placeholder || config.showCharsLeft) {
+    // Guarded: the modernized Garnish has no NiceText, and `craft-input`'s
+    // own `showCharsLeft` covers it where that namespace is in play.
+    if ((config.placeholder || config.showCharsLeft) && Garnish.NiceText) {
       new Garnish.NiceText($input);
     }
 
@@ -535,7 +537,11 @@ Craft.ui = {
     if (config.includeSortActions) {
       new Craft.SortableCheckboxSelect($container);
     } else {
-      new Garnish.CheckboxSelect($container);
+      // Guarded: superseded by the CheckboxSelect component where the
+      // modernized Garnish owns the namespace.
+      if (Garnish.CheckboxSelect) {
+        new Garnish.CheckboxSelect($container);
+      }
 
       if (config.sortable) {
         const dragSort = new Garnish.DragSort(

packages/craftcms-ui/src/components/combobox/combobox-form.browser.test.ts

@@ -0,0 +1,91 @@
+import {beforeEach, expect, it} from 'vite-plus/test';
+import type CraftCombobox from './combobox.js';
+import './combobox.js';
+import '../../styles/cp.css';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+/**
+ * A single-choice combobox in a plain form — the shape a page that posts itself
+ * uses, rather than going through an Inertia form.
+ */
+async function fixture(
+  configure: (control: CraftCombobox) => void = () => {}
+): Promise<{control: CraftCombobox; form: HTMLFormElement}> {
+  const control = document.createElement('craft-combobox') as CraftCombobox;
+  control.setAttribute('name', 'apiVersion');
+  control.options = [
+    {label: '2026-01', value: '2026-01'},
+    {label: '2026-04', value: '2026-04'},
+  ];
+  configure(control);
+
+  const form = document.createElement('form');
+  form.append(control);
+  document.body.append(form);
+  await control.updateComplete;
+  // Lion adopts a requested `model-value` only once the option naming it has
+  // registered, so the value lands a tick after the first render.
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+  await control.updateComplete;
+
+  return {control, form};
+}
+
+const entries = (form: HTMLFormElement) => [...new FormData(form).entries()];
+
+it('posts its value under the host name', async () => {
+  const {control, form} = await fixture((c) =>
+    c.setAttribute('model-value', '2026-01')
+  );
+
+  expect(entries(form)).toEqual([['apiVersion', '2026-01']]);
+
+  // Changing the selection changes what the form carries, so a save writes the
+  // value the field is showing.
+  control.modelValue = '2026-04';
+  await control.updateComplete;
+
+  expect(entries(form)).toEqual([['apiVersion', '2026-04']]);
+});
+
+it('posts a custom value when it does not match an option', async () => {
+  const {control, form} = await fixture((c) => {
+    c.requireOptionMatch = false;
+    c.setAttribute('model-value', '$SHOPIFY_API_VERSION');
+  });
+
+  expect(entries(form)).toEqual([['apiVersion', '$SHOPIFY_API_VERSION']]);
+  expect(control.modelValue).toBe('$SHOPIFY_API_VERSION');
+});
+
+it('posts a value its markup carried, with the options as markup too', async () => {
+  // How a server-rendered page arrives: both `model-value` and `options` are
+  // attributes on the element, and it upgrades with them already set.
+  const options = JSON.stringify([
+    {label: '$SHOPIFY_API_VERSION', value: '$SHOPIFY_API_VERSION'},
+  ]);
+  document.body.innerHTML = `<form><craft-combobox name="folderPath" model-value="@webroot/cache/blitz" allow-custom-choice options='${options}'></craft-combobox></form>`;
+
+  const form = document.querySelector('form')!;
+  const control = document.querySelector('craft-combobox') as CraftCombobox;
+  await control.updateComplete;
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+  await control.updateComplete;
+
+  expect(control.modelValue).toBe('@webroot/cache/blitz');
+  expect(entries(form)).toEqual([['folderPath', '@webroot/cache/blitz']]);
+});
+
+it('posts nothing while disabled', async () => {
+  const {control, form} = await fixture((c) => {
+    c.setAttribute('model-value', '2026-01');
+    c.disabled = true;
+  });
+
+  await control.updateComplete;
+
+  expect(entries(form)).toEqual([]);
+});

packages/craftcms-ui/src/components/combobox/combobox-options.browser.test.ts

@@ -0,0 +1,73 @@
+import {beforeEach, expect, it} from 'vite-plus/test';
+import type CraftCombobox from './combobox.js';
+import './combobox.js';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+async function fixture(
+  options: CraftCombobox['options']
+): Promise<CraftCombobox> {
+  const control = document.createElement('craft-combobox') as CraftCombobox;
+  control.options = options;
+  document.body.append(control);
+  await control.updateComplete;
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+  await control.updateComplete;
+
+  return control;
+}
+
+it('colours an option’s indicator', async () => {
+  const control = await fixture([
+    {label: 'Online', value: 'true', data: {indicator: {fill: 'success'}}},
+    {label: 'Offline', value: 'false', data: {indicator: {fill: 'danger'}}},
+  ]);
+
+  const fills = [...control.querySelectorAll('craft-indicator')].map((el) =>
+    el.getAttribute('fill')
+  );
+
+  expect(fills).toEqual(['success', 'danger']);
+});
+
+it('leaves an indicator without a fill on the component’s default', async () => {
+  const control = await fixture([
+    {label: 'Plain', value: 'plain', data: {indicator: {}}},
+  ]);
+
+  const indicator = control.querySelector('craft-indicator')!;
+
+  expect(indicator.getAttribute('fill')).toBe('var(--c-color-fill-loud)');
+});
+
+it('renders an indicator’s appearance', async () => {
+  const control = await fixture([
+    {label: 'Off', value: 'off', data: {indicator: {appearance: 'outline'}}},
+  ]);
+
+  expect(
+    control.querySelector('craft-indicator')!.getAttribute('appearance')
+  ).toBe('outline');
+});
+
+it('colours an option’s icon', async () => {
+  const control = await fixture([
+    {label: 'Red', value: 'red', data: {icon: 'circle', color: 'danger'}},
+  ]);
+
+  expect(control.querySelector('craft-icon')!.getAttribute('style')).toContain(
+    '--icon-color: danger'
+  );
+});
+
+it('leaves an icon without a colour unstyled', async () => {
+  const control = await fixture([
+    {label: 'Plain', value: 'plain', data: {icon: 'circle'}},
+  ]);
+
+  expect(control.querySelector('craft-icon')!.hasAttribute('style')).toBe(
+    false
+  );
+});

packages/craftcms-ui/src/components/combobox/combobox.stories.ts

@@ -16,8 +16,8 @@ const countries: ComboboxItem[] = [
 ];
 
 const statuses: ComboboxItem[] = [
-  {label: 'Online', value: 'true', data: {indicator: {variant: 'success'}}},
-  {label: 'Offline', value: 'false', data: {indicator: {variant: 'danger'}}},
+  {label: 'Online', value: 'true', data: {indicator: {fill: 'success'}}},
+  {label: 'Offline', value: 'false', data: {indicator: {fill: 'danger'}}},
 ];
 
 const grouped: ComboboxItem[] = [