@spree/dashboard-ui 1.0.0-beta.8 → 1.0.0-rc.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spree/dashboard-ui",
   "license": "MIT",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-rc.1",
   "description": "Spree Dashboard design system — shadcn primitives, headless composed components, and design tokens. Source-only package; consumers compile via their own Vite/Tailwind setup. Developer Preview.",
   "author": "Vendo Connect Inc.",
   "homepage": "https://spreecommerce.org",
@@ -48,6 +48,15 @@
   },
   "dependencies": {
     "@base-ui/react": "1.8.0",
+    "@codemirror/autocomplete": "6.20.3",
+    "@codemirror/commands": "6.11.1",
+    "@codemirror/lang-html": "6.4.12",
+    "@codemirror/lang-liquid": "6.3.3",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/lint": "6.9.7",
+    "@codemirror/search": "6.7.2",
+    "@codemirror/state": "6.7.6",
+    "@codemirror/view": "6.43.13",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",

package/src/hooks/use-debounced-value.ts

@@ -0,0 +1,13 @@
+import { useEffect, useState } from 'react'
+
+/** The value, once it has stopped changing for `delayMs`. */
+export function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value)
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs)
+    return () => clearTimeout(id)
+  }, [value, delayMs])
+
+  return debounced
+}

package/src/index.ts

@@ -12,6 +12,7 @@
 // CSS lives at `@spree/dashboard-ui/styles.css` — import once from your Vite app.
 
 export * from './hooks/use-copy-to-clipboard'
+export * from './hooks/use-debounced-value'
 export { useIsMobile } from './hooks/use-mobile'
 export * from './hooks/use-prefers-reduced-motion'
 export * from './hooks/use-scrolled'
@@ -65,6 +66,8 @@ export * from './spree/return-dialogs'
 // `@spree/dashboard-ui/spree/json-preview-drawer` and
 // `@spree/dashboard-ui/spree/json-value-view`. Types are available the same
 // way — `import { type JsonPreviewDrawerProps } from '@spree/dashboard-ui/spree/json-preview-drawer'`.
+// CodeEditor (CodeMirror) is deep-imported for the same reason:
+// `@spree/dashboard-ui/ui/code-editor`.
 
 export * from './spree/external-link'
 export * from './spree/language-menu-items'

package/src/spree/calculator-summary.tsx

@@ -85,6 +85,7 @@ export function formatCalculatorSummary(
  * - `*_percent` decimals → `N%`.
  * - `currency` strings → omitted (folded into the money formatting).
  * - booleans → humanized key when true; skipped when false.
+ * - lists (tiers) → their length; other objects → omitted.
  * - everything else → `key: value`.
  */
 function formatField(
@@ -105,6 +106,10 @@ function formatField(
   if (field.type === 'boolean') {
     return value ? humanize(field.key) : null
   }
+  if (field.type === 'array') {
+    return Array.isArray(value) && value.length ? `${humanize(field.key)}: ${value.length}` : null
+  }
+  if (field.type === 'hash') return null
   return `${humanize(field.key)}: ${value}`
 }
 

package/src/spree/data-grid/fill-handle.tsx

@@ -130,7 +130,6 @@ export function FillHandle({ gridRef }: { gridRef: React.RefObject<HTMLElement |
 
   return (
     <div
-      // biome-ignore lint/a11y/useSemanticElements: this is a drag handle, not actionable on its own
       role="presentation"
       onPointerDown={onPointerDown}
       onPointerMove={onPointerMove}

package/src/spree/icons.ts

@@ -69,6 +69,7 @@ export {
   GlobeLockIcon,
   GripVerticalIcon,
   HandCoinsIcon,
+  HistoryIcon,
   HomeIcon,
   ImageIcon,
   ImagePlusIcon,
@@ -134,6 +135,7 @@ export {
   ShieldIcon,
   ShoppingCartIcon,
   SlidersHorizontalIcon,
+  SmartphoneIcon,
   SparklesIcon,
   SplitIcon,
   SquareTextIcon,

package/src/spree/post-sale-create-dialogs.tsx

@@ -98,10 +98,20 @@ export function CreateReturnDialog({
   )
 }
 
-/** A line the claim can name, with what one unit of it cost. */
+/** A line the claim can name, with what the customer paid for it. */
 export type ClaimableLine = PostSaleUnit & {
-  /** Unit price, used to default the refund to what was actually paid. */
-  price?: string | null
+  /** The whole line after discounts, used to default the refund to what was actually paid. */
+  discountedAmount?: string | null
+  /** Tax charged on top of the line's price, which a claim refunds with it. */
+  additionalTaxTotal?: string | null
+}
+
+/** What the customer paid for `quantity` units of the line, or blank when that is unknown. */
+function paidForUnits(line: ClaimableLine, quantity: number): string {
+  const paid = Number(line.discountedAmount) + Number(line.additionalTaxTotal ?? 0)
+  if (quantity <= 0 || line.discountedAmount == null || !Number.isFinite(paid)) return ''
+
+  return ((paid * quantity) / line.quantity).toFixed(2)
 }
 
 /**
@@ -138,6 +148,7 @@ export function CreateClaimDialog({
   const { t } = useTranslation()
   const [selection, setSelection] = useState<PostSaleSelection>({})
   const [amounts, setAmounts] = useState<Record<string, string>>({})
+  const [typedAmounts, setTypedAmounts] = useState<Record<string, boolean>>({})
   const [memo, setMemo] = useState('')
 
   const chosen = selectedUnits(selection)
@@ -173,16 +184,13 @@ export function CreateClaimDialog({
                           Math.min(Number(event.target.value), line.quantity),
                         )
                         setSelection({ ...selection, [line.id]: quantity })
-                        // Default the refund to what was paid for those units;
-                        // the merchant can still overwrite it.
-                        if (quantity > 0 && !amounts[line.id]) {
-                          const unitPrice = Number(line.price)
-                          if (Number.isFinite(unitPrice)) {
-                            setAmounts((current) => ({
-                              ...current,
-                              [line.id]: (unitPrice * quantity).toFixed(2),
-                            }))
-                          }
+                        // The refund follows what was paid for the chosen units
+                        // until the merchant types an amount of their own.
+                        if (!typedAmounts[line.id]) {
+                          setAmounts((current) => ({
+                            ...current,
+                            [line.id]: paidForUnits(line, quantity),
+                          }))
                         }
                       }}
                     />
@@ -202,9 +210,14 @@ export function CreateClaimDialog({
                           step="0.01"
                           min="0"
                           value={amounts[line.id] ?? ''}
-                          onChange={(event) =>
+                          onChange={(event) => {
                             setAmounts({ ...amounts, [line.id]: event.target.value })
-                          }
+                            // Clearing the field hands it back to the quantity.
+                            setTypedAmounts({
+                              ...typedAmounts,
+                              [line.id]: event.target.value !== '',
+                            })
+                          }}
                         />
                       </InputGroup>
                     </Field>

package/src/spree/return-dialogs.tsx

@@ -9,7 +9,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from '../ui/dialog'
-import { Field, FieldLabel } from '../ui/field'
+import { Field, FieldDescription, FieldLabel } from '../ui/field'
 import { Input } from '../ui/input'
 import { InputGroup, InputGroupAddon, InputGroupInput, InputGroupText } from '../ui/input-group'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
@@ -139,20 +139,68 @@ export function ReturnReceiveDialog({
   )
 }
 
+/** True when a received return is owed nothing, so completing it moves no money. */
+export function returnOwesNothing(refundableTotal: string): boolean {
+  return Number(refundableTotal) === 0
+}
+
+export type ReturnRefundFigures = {
+  status: string
+  refund_total: string
+  display_refund_total: string
+  refunded_total: string
+  display_refunded_total: string
+}
+
 /**
- * Gives the money back: how much, and by what means.
+ * What a return's card reports: what it is owed until money goes back, then
+ * what actually went back — which a merchant keeping a restocking fee makes
+ * less than it was owed, so that case also names the full amount. Money that
+ * went back counts even before the return is marked refunded: a refund that
+ * succeeded on one payment and was declined on the next leaves it received.
+ */
+export function returnRefundSummary(
+  returnRecord: ReturnRefundFigures,
+):
+  | { kind: 'owed'; amount: string }
+  | { kind: 'refunded'; amount: string }
+  | { kind: 'refunded_short'; amount: string; total: string } {
+  const refunded = Number(returnRecord.refunded_total)
+
+  if (returnRecord.status !== 'refunded' && refunded === 0) {
+    return { kind: 'owed', amount: returnRecord.display_refund_total }
+  }
+
+  if (refunded < Number(returnRecord.refund_total)) {
+    return {
+      kind: 'refunded_short',
+      amount: returnRecord.display_refunded_total,
+      total: returnRecord.display_refund_total,
+    }
+  }
+
+  return { kind: 'refunded', amount: returnRecord.display_refunded_total }
+}
+
+/**
+ * Gives the money back: how much, and by what means. A return owed nothing
+ * (a free gift sent back) is completed instead, with nothing to choose.
  *
  * The currency symbol comes from the caller — the operator's panel reads it
  * from the store it is looking at, and a seller has no currency of their own.
+ * `refundTaxTotal` is the formatted tax inside `refundableTotal`, shown so a
+ * merchant knows the pre-filled amount gives the tax back too.
  */
 export function ReturnRefundDialog({
   refundableTotal,
+  refundTaxTotal,
   currencySymbol,
   onClose,
   onSubmit,
   pending = false,
 }: {
   refundableTotal: string
+  refundTaxTotal?: string
   currencySymbol: string
   onClose: () => void
   onSubmit: (params: { refundMethod: RefundMethod; amount?: string }) => void
@@ -161,6 +209,7 @@ export function ReturnRefundDialog({
   const { t } = useTranslation()
   const [refundMethod, setRefundMethod] = useState<RefundMethod>('original_payment')
   const [amount, setAmount] = useState(refundableTotal)
+  const owesNothing = returnOwesNothing(refundableTotal)
 
   const methodOptions = [
     {
@@ -177,48 +226,67 @@ export function ReturnRefundDialog({
     <Dialog open onOpenChange={(open) => !open && onClose()}>
       <DialogContent>
         <DialogHeader>
-          <DialogTitle>{t('admin.pages.orders.detail.returns.refund_title')}</DialogTitle>
+          <DialogTitle>
+            {owesNothing
+              ? t('admin.pages.orders.detail.returns.complete_title')
+              : t('admin.pages.orders.detail.returns.refund_title')}
+          </DialogTitle>
         </DialogHeader>
         <DialogBody className="flex flex-col gap-4">
-          <Field>
-            <FieldLabel htmlFor="refund-amount">
-              {t('admin.pages.orders.detail.returns.refund_amount')}
-            </FieldLabel>
-            <InputGroup>
-              <InputGroupAddon>
-                <InputGroupText>{currencySymbol}</InputGroupText>
-              </InputGroupAddon>
-              <InputGroupInput
-                id="refund-amount"
-                type="number"
-                step="0.01"
-                min="0"
-                value={amount}
-                onChange={(event) => setAmount(event.target.value)}
-              />
-            </InputGroup>
-          </Field>
-          <Field>
-            <FieldLabel htmlFor="refund-method">
-              {t('admin.pages.orders.detail.returns.refund_method')}
-            </FieldLabel>
-            <Select
-              items={methodOptions}
-              value={refundMethod}
-              onValueChange={(value) => setRefundMethod(value as RefundMethod)}
-            >
-              <SelectTrigger id="refund-method">
-                <SelectValue />
-              </SelectTrigger>
-              <SelectContent>
-                {methodOptions.map((option) => (
-                  <SelectItem key={option.value} value={option.value}>
-                    {option.label}
-                  </SelectItem>
-                ))}
-              </SelectContent>
-            </Select>
-          </Field>
+          {owesNothing ? (
+            <p className="text-muted-foreground text-sm">
+              {t('admin.pages.orders.detail.returns.nothing_owed')}
+            </p>
+          ) : (
+            <>
+              <Field>
+                <FieldLabel htmlFor="refund-amount">
+                  {t('admin.pages.orders.detail.returns.refund_amount')}
+                </FieldLabel>
+                <InputGroup>
+                  <InputGroupAddon>
+                    <InputGroupText>{currencySymbol}</InputGroupText>
+                  </InputGroupAddon>
+                  <InputGroupInput
+                    id="refund-amount"
+                    type="number"
+                    step="0.01"
+                    min="0"
+                    value={amount}
+                    onChange={(event) => setAmount(event.target.value)}
+                  />
+                </InputGroup>
+                {refundTaxTotal && (
+                  <FieldDescription>
+                    {t('admin.pages.orders.detail.returns.refund_includes_tax', {
+                      tax: refundTaxTotal,
+                    })}
+                  </FieldDescription>
+                )}
+              </Field>
+              <Field>
+                <FieldLabel htmlFor="refund-method">
+                  {t('admin.pages.orders.detail.returns.refund_method')}
+                </FieldLabel>
+                <Select
+                  items={methodOptions}
+                  value={refundMethod}
+                  onValueChange={(value) => setRefundMethod(value as RefundMethod)}
+                >
+                  <SelectTrigger id="refund-method">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {methodOptions.map((option) => (
+                      <SelectItem key={option.value} value={option.value}>
+                        {option.label}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </Field>
+            </>
+          )}
         </DialogBody>
         <DialogFooter>
           <Button type="button" variant="outline" onClick={onClose} disabled={pending}>
@@ -227,9 +295,11 @@ export function ReturnRefundDialog({
           <Button
             type="button"
             disabled={pending}
-            onClick={() => onSubmit({ refundMethod, amount })}
+            onClick={() => onSubmit({ refundMethod, amount: owesNothing ? undefined : amount })}
           >
-            {t('admin.pages.orders.detail.returns.actions.refund')}
+            {owesNothing
+              ? t('admin.pages.orders.detail.returns.actions.complete')
+              : t('admin.pages.orders.detail.returns.actions.refund')}
           </Button>
         </DialogFooter>
       </DialogContent>

package/src/spree/route-error-boundary.tsx

@@ -16,8 +16,11 @@ interface ErrorStateProps {
   title?: ReactNode
   /** Smaller text below the title. Pass an Error and we'll show its message. */
   description?: ReactNode
-  /** Error object — when supplied, its message is shown if `description` is omitted. */
-  error?: Error | null
+  /**
+   * Whatever was thrown — routers hand it over as `unknown`. When it is an
+   * Error, its message is shown if `description` is omitted.
+   */
+  error?: unknown
   /** Called by the retry button. When omitted, the button is hidden. */
   onRetry?: () => void
   /** Override the retry label. Default "Try again". */
@@ -33,7 +36,10 @@ export function ErrorState({ title, description, error, onRetry, retryLabel }: E
   const { t } = useTranslation()
   const resolvedTitle = title ?? t('admin.errors.generic')
   const resolvedRetryLabel = retryLabel ?? t('admin.components.error_state.retry')
-  const message = description ?? error?.message ?? t('admin.errors.unexpected_retry')
+  const message =
+    description ??
+    (error instanceof Error ? error.message : undefined) ??
+    t('admin.errors.unexpected_retry')
 
   return (
     <Empty>

package/src/styles.css

@@ -153,7 +153,7 @@
      sheet rather than a surface floating above it, so its edge only has to
      suggest where the region ends. Used by `CardContent`'s frame; a dialog or
      the sheet itself must keep --border, or the shell loses its outline. */
-  --border-card: color-mix(in srgb, var(--border-base) 60%, transparent);
+  --border-card: color-mix(in srgb, var(--border-base) 70%, transparent);
   /* Dividers *inside* a container — card header/footer splits, dialog and
      sheet separators, table row rules.
 
@@ -224,11 +224,9 @@
   --sidebar-foreground: oklch(26.8% 0.007 34.298);
   --sidebar-primary: var(--primary);
   --sidebar-primary-foreground: var(--primary-foreground);
-  --sidebar-accent: var(--accent);
-  --sidebar-accent-foreground: var(--accent-foreground);
-  --sidebar-accent-strong: var(--accent-strong);
+  --sidebar-accent: oklch(92.3% 0.003 48.717);
+  --sidebar-accent-foreground: var(--accent-foreground);;
   --sidebar-accent-hover: var(--accent-strong);
-  --sidebar-accent-strong-hover: var(--accent-strong-hover);
   /* Matches the rule the top bar draws, so every edge framing the shell —
      the sidebar's, the top bar's, the settings header's — is one weight. */
   --sidebar-border: color-mix(in srgb, var(--border) 75%, transparent);
@@ -327,7 +325,7 @@
      hairline weight. */
   --border-base: oklch(1 0 0 / 16%);
   --border: var(--border-base);
-  --border-card: color-mix(in srgb, var(--border-base) 50%, transparent);
+  --border-card: color-mix(in srgb, var(--border-base) 70%, transparent);
   --border-subtle: color-mix(in srgb, var(--border-base) 50%, transparent);
   /* Light mode darkens the control edge away from the card; dark mode lightens
      it. Not the light value inverted — measured on this theme's own surfaces:
@@ -376,9 +374,7 @@
   --sidebar-primary-foreground: var(--primary-foreground);
   --sidebar-accent: var(--accent);
   --sidebar-accent-foreground: var(--accent-foreground);
-  --sidebar-accent-strong: var(--accent-strong);
   --sidebar-accent-hover: var(--accent-hover);
-  --sidebar-accent-strong-hover: var(--accent-strong-hover);
   /* Matches the rule the top bar draws, so every edge framing the shell —
      the sidebar's, the top bar's, the settings header's — is one weight. */
   --sidebar-border: color-mix(in srgb, var(--border) 75%, transparent);
@@ -486,9 +482,7 @@
   --color-sidebar-ring: var(--sidebar-ring);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-accent-strong: var(--sidebar-accent-strong);
   --color-sidebar-accent-hover: var(--sidebar-accent-hover);
-  --color-sidebar-accent-strong-hover: var(--sidebar-accent-strong-hover);
   --color-sidebar-accent: var(--sidebar-accent);
   --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
   --color-sidebar-primary: var(--sidebar-primary);

package/src/ui/button.tsx

@@ -13,7 +13,7 @@ const buttonVariants = cva(
         // and it was the only variant with no lift at all.
         default: 'bg-primary text-primary-foreground shadow-xs hover:bg-primary/85',
         outline:
-          'border-border bg-card shadow-xs text-foreground hover:bg-accent hover:text-foreground aria-expanded:bg-accent',
+          'border-border/80 bg-card shadow-xs text-foreground hover:bg-accent hover:text-foreground aria-expanded:bg-accent',
         // `group-hover/row:` — inside a hovered table row the row already wears
         // --accent, so repeating it here leaves the button at 1.03:1 against its
         // own background: invisible exactly when the pointer is on it. On a

package/src/ui/code-editor.tsx

@@ -0,0 +1,248 @@
+import {
+  autocompletion,
+  closeBrackets,
+  closeBracketsKeymap,
+  completionKeymap,
+} from '@codemirror/autocomplete'
+import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands'
+import { html } from '@codemirror/lang-html'
+import { closePercentBrace, liquid } from '@codemirror/lang-liquid'
+import {
+  bracketMatching,
+  defaultHighlightStyle,
+  foldGutter,
+  indentOnInput,
+  syntaxHighlighting,
+} from '@codemirror/language'
+import { type Diagnostic, lintGutter, setDiagnostics } from '@codemirror/lint'
+import { highlightSelectionMatches, searchKeymap } from '@codemirror/search'
+import { Compartment, EditorState } from '@codemirror/state'
+import {
+  drawSelection,
+  EditorView,
+  highlightActiveLine,
+  highlightActiveLineGutter,
+  keymap,
+  lineNumbers,
+} from '@codemirror/view'
+import { type Ref, useEffect, useImperativeHandle, useRef } from 'react'
+import { cn } from '../lib/utils'
+
+export interface CodeEditorCompletion {
+  /** A variable, or a dotted path to one of its fields (`order.number`). */
+  label: string
+  /** Short type or value shown next to the label. */
+  detail?: string
+  /** Longer description shown beside the list. */
+  info?: string
+}
+
+export interface CodeEditorDiagnostic {
+  /** 1-based line the problem is on; problems without one mark the first line. */
+  line?: number | null
+  message: string
+}
+
+export interface CodeEditorHandle {
+  /** Replaces the selection with `text`, leaves the cursor after it and focuses the editor. */
+  insert: (text: string) => void
+}
+
+export interface CodeEditorProps {
+  ref?: Ref<CodeEditorHandle>
+  value: string
+  onChange?: (value: string) => void
+  /** Variables offered after `{{` and their fields after a dot. */
+  completions?: CodeEditorCompletion[]
+  /** Filters offered after `|`. */
+  filters?: CodeEditorCompletion[]
+  diagnostics?: CodeEditorDiagnostic[]
+  readOnly?: boolean
+  /** Called on Cmd/Ctrl+S. */
+  onSave?: () => void
+  'aria-label'?: string
+  className?: string
+}
+
+const theme = EditorView.theme({
+  '&': {
+    backgroundColor: 'var(--card)',
+    color: 'var(--foreground)',
+    fontSize: '13px',
+    height: '100%',
+  },
+  '.cm-scroller': { fontFamily: 'var(--font-mono, ui-monospace, monospace)', lineHeight: '1.6' },
+  '.cm-content': { caretColor: 'var(--foreground)' },
+  '.cm-gutters': {
+    backgroundColor: 'var(--background)',
+    color: 'var(--muted-foreground)',
+    borderRight: '1px solid var(--border)',
+  },
+  '.cm-activeLine, .cm-activeLineGutter': {
+    backgroundColor: 'color-mix(in srgb, var(--accent) 60%, transparent)',
+  },
+  '&.cm-focused': { outline: 'none' },
+  '&.cm-focused .cm-selectionBackground, .cm-selectionBackground': {
+    backgroundColor: 'color-mix(in srgb, var(--ring) 20%, transparent)',
+  },
+  '.cm-tooltip': {
+    backgroundColor: 'var(--popover)',
+    color: 'var(--popover-foreground)',
+    border: '1px solid var(--border)',
+    borderRadius: '8px',
+  },
+})
+
+const NO_COMPLETIONS: CodeEditorCompletion[] = []
+const NO_DIAGNOSTICS: CodeEditorDiagnostic[] = []
+
+function toDiagnostics(state: EditorState, problems: CodeEditorDiagnostic[]): Diagnostic[] {
+  return problems.map((problem) => {
+    const lineNumber = Math.min(Math.max(problem.line ?? 1, 1), state.doc.lines)
+    const line = state.doc.line(lineNumber)
+    return { from: line.from, to: line.to, severity: 'error', message: problem.message }
+  })
+}
+
+/**
+ * A code editor for Liquid templates written in HTML or MJML, with variable
+ * and filter completion, inline problems and the usual editing keys.
+ */
+function CodeEditor({
+  value,
+  onChange,
+  completions = NO_COMPLETIONS,
+  filters = NO_COMPLETIONS,
+  diagnostics = NO_DIAGNOSTICS,
+  readOnly = false,
+  onSave,
+  className,
+  ref,
+  ...props
+}: CodeEditorProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const viewRef = useRef<EditorView | null>(null)
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      insert: (text) => {
+        const view = viewRef.current
+        if (!view || view.state.readOnly) return
+        view.dispatch(view.state.replaceSelection(text), { scrollIntoView: true })
+        view.focus()
+      },
+    }),
+    [],
+  )
+  const languageCompartment = useRef(new Compartment())
+  const readOnlyCompartment = useRef(new Compartment())
+  const callbacks = useRef({ onChange, onSave })
+  callbacks.current = { onChange, onSave }
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the view is created once; later props flow in through the effects below
+  useEffect(() => {
+    if (!containerRef.current) return
+
+    const view = new EditorView({
+      parent: containerRef.current,
+      state: EditorState.create({
+        doc: value,
+        extensions: [
+          lineNumbers(),
+          highlightActiveLineGutter(),
+          foldGutter(),
+          history(),
+          drawSelection(),
+          indentOnInput(),
+          bracketMatching(),
+          closeBrackets(),
+          closePercentBrace,
+          highlightActiveLine(),
+          highlightSelectionMatches(),
+          autocompletion(),
+          lintGutter(),
+          syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+          EditorView.lineWrapping,
+          theme,
+          languageCompartment.current.of([]),
+          readOnlyCompartment.current.of(EditorState.readOnly.of(readOnly)),
+          keymap.of([
+            {
+              key: 'Mod-s',
+              preventDefault: true,
+              run: () => {
+                callbacks.current.onSave?.()
+                return true
+              },
+            },
+            ...closeBracketsKeymap,
+            ...defaultKeymap,
+            ...searchKeymap,
+            ...historyKeymap,
+            ...completionKeymap,
+            indentWithTab,
+          ]),
+          EditorView.updateListener.of((update) => {
+            if (update.docChanged) callbacks.current.onChange?.(update.state.doc.toString())
+          }),
+          EditorView.contentAttributes.of({ 'aria-label': props['aria-label'] ?? '' }),
+        ],
+      }),
+    })
+    viewRef.current = view
+
+    return () => {
+      view.destroy()
+      viewRef.current = null
+    }
+  }, [])
+
+  useEffect(() => {
+    const view = viewRef.current
+    if (!view || view.state.doc.toString() === value) return
+    view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: value } })
+  }, [value])
+
+  useEffect(() => {
+    const variables = completions.filter((completion) => !completion.label.includes('.'))
+    const language = liquid({
+      base: html(),
+      variables,
+      filters,
+      properties: (path) => {
+        const prefix = `${path.join('.')}.`
+        return completions
+          .filter((completion) => completion.label.startsWith(prefix))
+          .map((completion) => ({ ...completion, label: completion.label.slice(prefix.length) }))
+          .filter((completion) => !completion.label.includes('.'))
+      },
+    })
+    viewRef.current?.dispatch({ effects: languageCompartment.current.reconfigure(language) })
+  }, [completions, filters])
+
+  useEffect(() => {
+    viewRef.current?.dispatch({
+      effects: readOnlyCompartment.current.reconfigure(EditorState.readOnly.of(readOnly)),
+    })
+  }, [readOnly])
+
+  useEffect(() => {
+    const view = viewRef.current
+    if (!view) return
+    view.dispatch(setDiagnostics(view.state, toDiagnostics(view.state, diagnostics)))
+  }, [diagnostics])
+
+  return (
+    <div
+      ref={containerRef}
+      data-slot="code-editor"
+      className={cn(
+        'min-h-64 overflow-hidden rounded-md border border-border bg-card shadow-control focus-within:border-blue-500 focus-within:shadow-[0_0_0_3px_color-mix(in_srgb,var(--ring)_15%,transparent)]',
+        className,
+      )}
+    />
+  )
+}
+
+export { CodeEditor }

package/src/ui/combobox.tsx

@@ -8,7 +8,33 @@ import { CheckIcon, ChevronDownIcon, XIcon } from '../spree/icons'
 import { Button } from './button'
 import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from './input-group'
 
-const Combobox = ComboboxPrimitive.Root
+/**
+ * Base UI empties a multi-select when Escape is pressed with its popup closed,
+ * and picking a searched result closes the popup, so the Escape meant to
+ * dismiss the search silently wiped every chip. Chips are removed only through
+ * their own remove button or Backspace, and the Escape passes on to whatever
+ * encloses the picker, such as a sheet, as it does for an empty one.
+ */
+function Combobox<Value, Multiple extends boolean | undefined = false, Item = Value>(
+  props: ComboboxPrimitive.Root.Props<Value, Multiple, Item>,
+) {
+  const { multiple, onValueChange } = props
+  if (!multiple) return <ComboboxPrimitive.Root {...props} />
+
+  return (
+    <ComboboxPrimitive.Root
+      {...props}
+      onValueChange={(value, eventDetails) => {
+        if (eventDetails.reason === 'escape-key') {
+          eventDetails.cancel()
+          eventDetails.allowPropagation()
+          return
+        }
+        onValueChange?.(value, eventDetails)
+      }}
+    />
+  )
+}
 
 function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {
   return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />

package/src/ui/sidebar.tsx

@@ -276,7 +276,7 @@ function Sidebar({
           'fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] md:flex',
           // Adjust the padding for floating and inset variants.
           variant === 'floating' || variant === 'inset'
-            ? 'p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]'
+            ? 'py-2 px-1 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]'
             : 'group-data-[collapsible=icon]:w-(--sidebar-width-icon)',
           className,
         )}
@@ -402,7 +402,7 @@ function SidebarFooter({ className, ...props }: React.ComponentProps<'div'>) {
       data-slot="sidebar-footer"
       data-sidebar="footer"
       className={cn(
-        'flex flex-col gap-0 p-2 mt-auto border-t border-border-subtle group-data-[collapsible=icon]:px-0 group-data-[collapsible=icon]:items-center',
+        'flex flex-col gap-0 p-1.5 mt-auto border-t border-border-subtle group-data-[collapsible=icon]:px-0 group-data-[collapsible=icon]:items-center',
         className,
       )}
       {...props}