craft-garnish
Garnish — Craft CMS's built-in JavaScript UI toolkit for the control panel. ALWAYS load when writing, editing, or reviewing JavaScript that runs in the Craft CP — plugin CP assets, custom field type JS, element index JS, CP webpack config, or code importing garnishjs / referencing window.Garnish. Also for CP accessibility, keyboard interactions, drag-sort, and CP JS memory issues. Triggers on: Garnish.Base.extend, this.base(), init, setSettings, addListener, on/off/trigger, destroy, garnishjs, GarnishAsset, CpAsset, webpack externals, CP JavaScript, Craft.* pattern, Garnish.Modal, HUD, DisclosureMenu, MenuBtn, CustomSelect, ContextMenu, Select, modal/HUD popover, BaseDrag, DragSort, DragDrop, DragMove, onSortChange/onOptionSelect/onSelectionChange, NiceText, CheckboxSelect, MixedInput, MultiFunctionBtn, ESC_KEY/RETURN_KEY, activate/textchange events, UiLayerManager, registerShortcut, trapFocusWithin/releaseFocusWithin/setFocusWithin, ARIA helpers, focus management, aria-modal, aria-hid
michtio · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add michtio/craftcms-claude-skills --skill craft-garnish技能说明
name: craft-garnish description: "Garnish — Craft CMS's built-in JavaScript UI toolkit for the control panel. ALWAYS load when writing, editing, or reviewing JavaScript that runs in the Craft CP — plugin CP assets, custom field type JS, element index JS, CP webpack config, or code importing garnishjs / referencing window.Garnish. Also for CP accessibility, keyboard interactions, drag-sort, and CP JS memory issues. Triggers on: Garnish.Base.extend, this.base(), init, setSettings, addListener, on/off/trigger, destroy, garnishjs, GarnishAsset, CpAsset, webpack externals, CP JavaScript, Craft.* pattern, Garnish.Modal, HUD, DisclosureMenu, MenuBtn, CustomSelect, ContextMenu, Select, modal/HUD popover, BaseDrag, DragSort, DragDrop, DragMove, onSortChange/onOptionSelect/onSelectionChange, NiceText, CheckboxSelect, MixedInput, MultiFunctionBtn, ESC_KEY/RETURN_KEY, activate/textchange events, UiLayerManager, registerShortcut, trapFocusWithin/releaseFocusWithin/setFocusWithin, ARIA helpers, focus management, aria-modal, aria-hidden retained focus, inert attribute, focus trap, keyboard navigation CP, Craft.CP, Craft.Slideout, Craft.ElementEditor, Craft.sendActionRequest, CP memory leak, event listener cleanup, jQuery .on() in CP, custom slideout/overlay lifecycle, disable kills listeners, sidebar panel injected into the entry form, id-only inputs with no name attribute, host form swallows my fields, Enter key submits the entry form, lightswitch value in JS. Do NOT trigger for front-end JavaScript (Alpine, Vue, htmx) or Twig templates (craft-site)."
Garnish — Craft CMS Control Panel JavaScript Toolkit
Reference for Garnish, Craft CMS's built-in JavaScript UI framework. Covers the class system, UI widgets, drag interactions, form components, accessibility helpers, and integration with Craft's CP.
This skill is scoped to Garnish itself — the JavaScript library at src/web/assets/garnish/. For PHP-side plugin development (elements, controllers, services), see the craftcms skill. For CP template markup that Garnish widgets attach to, see the craftcms skill's cp.md reference.
Companion Skills — Load When Needed
craftcms— Load when the task involves PHP asset bundle classes, plugin architecture, or CP template markup that Garnish widgets attach to. Skip for pure JavaScript refactoring, Garnish API questions, or JS-only tasks.craft-php-guidelines— Load only when editing PHP files (asset bundle classes, controllers that register JS). Skip for pure JS work.
Documentation
- Garnish source:
src/web/assets/garnish/src/in the Craft CMS repository - No official external documentation exists — this skill IS the documentation.
Use WebFetch on Craft's class reference (https://docs.craftcms.com/api/v5/) when looking up PHP-side asset bundle registration.
Common Pitfalls (Cross-Cutting)
- Using jQuery
.on()directly instead ofthis.addListener()— listeners added via jQuery won't auto-clean ondestroy(), causing memory leaks. - Forgetting
this.base()when overridingdestroy()— parent cleanup (listener removal, event teardown) gets skipped. - Using
clickinstead ofactivateevent on non-<button>elements —activatehandles both click and keyboard (Space/Enter), making the UI accessible. - Fighting
UiLayerManagerby binding ESC directly — useGarnish.uiLayerManager.registerShortcut(Garnish.ESC_KEY, callback)so escape routes through the layer stack correctly. - Magic key code numbers instead of
Garnish.ESC_KEY,Garnish.RETURN_KEY, etc. — constants are self-documenting and consistent. - Instantiating Garnish widgets before the DOM is ready — Garnish requires jQuery and all dependencies loaded first; in plugin assets, rely on
CpAssetdependency chain. - Not calling
destroy()when removing widgets — orphaned listeners accumulate, especially in slideouts and live preview where DOM is repeatedly created/destroyed. - Importing Garnish into webpack bundles instead of using the external —
import Garnish from 'garnishjs'resolves towindow.Garnishvia webpack externals; bundling it duplicates 134KB. - Giving
nameattributes to inputs in a panel injected into another form (an entry-edit sidebar panel, a CP template hook) — the host form serializes them on save and your plugin's values are silently swallowed. Inputs are id-only, your JS reads them by id and posts to your own endpoint, and an Enter-key guard keeps the host form from submitting. Seeintegration.md(Panels Injected Into Another Form). - Using deprecated
Garnish.Menuinstead ofGarnish.CustomSelect—Menuis an alias kept for BC only. - Using deprecated
Garnish.escManagerorGarnish.shortcutManagerinstead ofGarnish.uiLayerManager— the newer manager provides layer-aware keyboard routing that respects the modal/menu stack.
Reference Files
Read the relevant reference file(s) for your task. Multiple files often apply together.
Task examples:
- "Create a modal dialog in a plugin's CP JS" → read
class-system.md+ui-widgets.md - "Add drag-to-reorder to a custom field type" → read
drag-system.md+class-system.md - "Build a custom CP widget class" → read
class-system.md+integration.md - "Add a disclosure menu to a CP template" → read
ui-widgets.md+integration.md - "Handle keyboard events in CP JavaScript" → read
utilities.md+class-system.md - "Create an inline editor HUD" → read
ui-widgets.md(HUD section) - "Make a selection interface for elements" → read
ui-widgets.md(Select section) - "Set up a plugin's webpack config for Garnish" → read
integration.md - "Custom element index class isn't loading" → read
integration.md(Element Index JS Loading) - "Load element index JS with Vite" → read
integration.md(Element Index JS Loading — Vite doesn't work for element index classes) - "Add ARIA attributes to a custom modal" → read
utilities.md(ARIA & Focus section) - "Build a custom slideout/overlay/launcher on Garni