From 1eea45ae77cdd45f3b0b88618a9577110ede4c0c Mon Sep 17 00:00:00 2001
From: tommy230 <tommy@godigitalalchemy.com>
Date: Mon, 28 Sep 2026 19:34:17 +0000
Subject: [PATCH] fix(import): keep the content a compound submit button wraps

base.submit was a leaf whose only content was the label string, with a
'Submit' fallback for buttons with no text. Submit buttons that carry an
icon instead of text (an inline svg, an icon-font <i>, an <img>) lost the
icon on import and published as the literal word "Submit".

base.submit now accepts children and renders them when it has any, falling
back to the label when it has none (the base.link contract, shared between
the publisher render and the canvas via forms/content.ts). The importer
recurses into submit buttons with element children instead of flattening
them to a label.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/features/html-import.md                  |  4 +-
 docs/features/modules.md                      |  2 +-
 docs/reference/module-engine.md               |  2 +
 .../htmlImport/structurePreservation.test.ts  |  6 +-
 .../htmlImport/submitButtonChildren.test.ts   | 99 +++++++++++++++++++
 src/core/htmlImport/rules.ts                  |  9 +-
 src/modules/base/forms/FormControls.tsx       |  6 +-
 src/modules/base/forms/content.ts             | 24 +++++
 src/modules/base/forms/index.ts               | 19 +++-
 9 files changed, 154 insertions(+), 17 deletions(-)
 create mode 100644 src/__tests__/htmlImport/submitButtonChildren.test.ts
 create mode 100644 src/modules/base/forms/content.ts

diff --git a/docs/features/html-import.md b/docs/features/html-import.md
index 7cb7bf493..a9a2815d6 100644
--- a/docs/features/html-import.md
+++ b/docs/features/html-import.md
@@ -108,7 +108,7 @@ Callers splice the fragment into the page tree via `insertImportedNodes(parentId
 | `select` | `base.select` | `fieldId`, `name`, `id`, `required`, `disabled`, `multiple` | Yes |
 | `optgroup` | `base.option-group` | `label`, `disabled` | Yes |
 | `option` | `base.option` | `value`, `label`, `selected`, `disabled` | No |
-| `button` | `base.button`, `base.submit` when submit-type / inside a form without a type, or `base.container` tagged `button` when a non-submit button wraps element children | `label`, `disabled` | No for text-only and for submit buttons; yes for compound non-submit buttons |
+| `button` | `base.button`, `base.submit` when submit-type / inside a form without a type, or `base.container` tagged `button` when a non-submit button wraps element children | `label`, `disabled` | No for text-only; yes when the button wraps element children |
 | `ul`, `ol` | `base.container` | `tag` = tag name | Yes |
 | `div`, `section`, `article`, `main`, `header`, `footer`, `nav`, `aside` | `base.container` | `tag` = tag name | Yes |
 | `area`, `base`, `br`, `col`, `embed`, `hr`, `link`, `meta`, `param`, `source`, `track`, `wbr` (void elements) | `base.container` | `tag: 'custom'`, `customTag` = tag name | **No** |
@@ -122,7 +122,7 @@ Callers splice the fragment into the page tree via `insertImportedNodes(parentId
 - **Direct text inside a recursing container is preserved.** The walker iterates `childNodes` (not just `children`): element children route through the rules, and each significant text node becomes a synthesized `base.text` child with `tag: 'none'` in document order. That no-wrapper text mode publishes back to bare text, so `<div class="num">98%</div>` and `<li>Buy milk</li>` import as containers holding their original text without adding selector-visible wrapper elements. Whitespace-only text (indentation between tags) is skipped; internal whitespace runs collapse to single spaces, and boundary spaces are kept when the text run sits between element siblings.
 - **`<body>` metadata is preserved separately.** Classes, safe HTML attributes (`id`, ARIA, `data-*`, etc.), and harvested inline styles on `<body>` are returned as `fragment.body` rather than inserted into `rootIds`. Full-site import applies them to `base.body`; paste-style HTML import can ignore them without changing the fragment structure.
 - `base.link` uses the prop `text` (not `label`). `base.button` uses `label` (not `text`). These match the module source.
-- **Button-like elements keep what they wrap.** `base.button` is `canHaveChildren: false`, so an `a.btn` or a `<button>` wrapping an icon, inline `<svg>` or `<img>` would import as a label-only leaf and lose the rest without saying so. Those recurse instead: a compound `.btn` anchor maps to `base.link` (keeping `href` and `target`), and a compound non-submit `<button>` maps to a `base.container` tagged `button`. Class names ride along as classIds, so `.btn` styling survives the module swap. Submit buttons stay `base.submit` even when compound, because `core/forms` identifies a form's submit control by that module id — so a compound submit button still keeps only its label.
+- **Button-like elements keep what they wrap.** `base.button` is `canHaveChildren: false`, so an `a.btn` or a `<button>` wrapping an icon, inline `<svg>` or `<img>` would import as a label-only leaf and lose the rest without saying so. Those recurse instead: a compound `.btn` anchor maps to `base.link` (keeping `href` and `target`), and a compound non-submit `<button>` maps to a `base.container` tagged `button`. Class names ride along as classIds, so `.btn` styling survives the module swap. Submit buttons stay `base.submit` even when compound, because `core/forms` identifies a form's submit control by that module id; `base.submit` accepts children, so an icon-only submit (an inline `<svg>`, an icon-font `<i>`, an `<img>`) keeps its icon as child nodes and the `label` prop is only the childless fallback.
 - `base.image` captures `src` and the authored `loading` / `decoding` / `fetchpriority` hints (unknown values keep the module defaults). `alt` is not a per-instance prop — it comes from the media library asset — so the walker reports it per node in `WalkResult.imageAlts` (an empty string is a deliberate decorative alt) and Site Import creates the media record with it.
 - **Form elements import as form primitives.** Third-party `<form>` elements default to `base.form` in `custom` mode, so they do not become CMS submission endpoints until an author binds them to a data table. Published CMS-native forms can round-trip their `data-instatic-*` form metadata. Plain labels become `base.label`; labels that wrap controls become a `base.container` with `customTag:'label'` so nested inputs are not dropped.
 - **Void elements** (`<br>`, `<hr>`, etc.) have their own rule that sits before the catch-all. They map to `base.container` with `tag:'custom'` + the real tag name, but with `recurse:false` so the produced node has no children. `<input>` is not part of this fallback anymore; it imports through the form-control rule. The canvas renderer (`ContainerEditor`) also guards against passing children (including the empty-container placeholder) to void element tags, because React throws if you do so.
diff --git a/docs/features/modules.md b/docs/features/modules.md
index b61509d49..687aaa87d 100644
--- a/docs/features/modules.md
+++ b/docs/features/modules.md
@@ -46,7 +46,7 @@ src/modules/base/
 ├── video/               — base.video (youtube.ts — ID parse + embed URL leaf)
 ├── list/                — base.list (items.ts — textarea item-splitting leaf)
 ├── loop/                — base.loop
-├── forms/               — base.form and form-control primitives
+├── forms/               — base.form and form-control primitives (content.ts: submit children/label rule)
 ├── visualComponentRef/  — base.visual-component-ref
 ├── slotOutlet/          — base.slot-outlet (VC author side)
 ├── slotInstance/        — base.slot-instance (VC consumer side)
diff --git a/docs/reference/module-engine.md b/docs/reference/module-engine.md
index 21142596f..162bcc770 100644
--- a/docs/reference/module-engine.md
+++ b/docs/reference/module-engine.md
@@ -260,6 +260,7 @@ Name the leaf after what it owns, not generically:
 |------------------|-----------------|-------------------------------------------------------|
 | `base.button`    | `anchor.ts`     | `resolveButtonAnchor()` — element decision (`<a>` vs `<button>`) |
 | `base.link`      | `content.ts`    | `linkUsesChildren()` — children/text fallback rule    |
+| `base.submit`    | `forms/content.ts` | `submitUsesChildren()` — children/label fallback rule |
 | `base.list`      | `items.ts`      | `parseItems()` — textarea → trimmed non-empty array   |
 | `base.video`     | `youtube.ts`    | `parseYoutubeId()`, `youtubeEmbedUrl()` — embed URL  |
 | `base.text`      | `tags.ts`       | `normalizeTag()`, `TextTag` — semantic tag coercion   |
@@ -424,6 +425,7 @@ The publisher emits a `<script type="importmap">` entry. `getMissingModuleDepend
   - `src/modules/base/shared/anchorTarget.ts` — `AnchorTargetSchema`, `anchorRel()` (cross-module shared vocabulary)
   - `src/modules/base/button/anchor.ts` — `resolveButtonAnchor()` (per-module shared leaf)
   - `src/modules/base/link/content.ts` — `linkUsesChildren()` (per-module shared leaf)
+  - `src/modules/base/forms/content.ts` — `submitUsesChildren()` (per-module shared leaf)
   - `src/modules/base/list/items.ts` — `parseItems()` (per-module shared leaf)
   - `src/modules/base/video/youtube.ts` — `parseYoutubeId()`, `youtubeEmbedUrl()` (per-module shared leaf)
   - `src/core/htmlAttributes/tags.ts` — `resolveHtmlTag`, `BUILTIN_HTML_TAGS`, `VOID_HTML_ELEMENTS`
diff --git a/src/__tests__/htmlImport/structurePreservation.test.ts b/src/__tests__/htmlImport/structurePreservation.test.ts
index 80d634176..740a0a053 100644
--- a/src/__tests__/htmlImport/structurePreservation.test.ts
+++ b/src/__tests__/htmlImport/structurePreservation.test.ts
@@ -125,12 +125,12 @@ describe('compound buttons keep what they wrap', () => {
     expect(root.children).toHaveLength(0)
   })
 
-  it('a submit button stays base.submit even when compound', () => {
+  it('a compound submit button stays base.submit and keeps its children', () => {
     // core/forms finds a form's submit control by module id, so a compound
-    // submit must not be re-tagged as a container. It keeps only its label.
+    // submit must not be re-tagged as a container; its content recurses.
     const r = importHtml('<form><button><svg viewBox="0 0 1 1"></svg><span>Send</span></button></form>')
     const submit = Object.values(r.nodes).find((n) => n.moduleId === 'base.submit')
     expect(submit).toBeDefined()
-    expect(submit!.children).toHaveLength(0)
+    expect(submit!.children).toHaveLength(2)
   })
 })
diff --git a/src/__tests__/htmlImport/submitButtonChildren.test.ts b/src/__tests__/htmlImport/submitButtonChildren.test.ts
new file mode 100644
index 000000000..ff8565930
--- /dev/null
+++ b/src/__tests__/htmlImport/submitButtonChildren.test.ts
@@ -0,0 +1,99 @@
+/**
+ * Icon-only submit buttons keep their icon through import and publish.
+ *
+ * base.submit was a leaf whose only content was the `label` string, with a
+ * 'Submit' fallback when the button had no text. Real markup often puts an
+ * icon there instead of text: a newsletter form's arrow as an inline `<svg>`,
+ * a search box's magnifier as an icon-font `<i>`, an `<img>` of a button
+ * graphic. Every one of them imported and published as the literal word
+ * "Submit". The importer now recurses into submit buttons with element
+ * children, and base.submit renders children when it has them, `label` when
+ * it doesn't: the base.link contract.
+ */
+import { describe, it, expect } from 'bun:test'
+import '@modules/base'
+import { importHtml } from '@core/htmlImport'
+import { SubmitModule } from '@modules/base/forms'
+
+/** Import `html` and return the base.submit node plus its resolved children. */
+function submitNodeOf(html: string) {
+  const result = importHtml(`<html><body>${html}</body></html>`)
+  const node = Object.values(result.nodes).find((n) => n.moduleId === 'base.submit')
+  if (!node) throw new Error('no base.submit node was produced')
+  return { node, kids: node.children.map((id) => result.nodes[id]!) }
+}
+
+describe('submit buttons with element children recurse', () => {
+  it('keeps an inline <svg> arrow as a base.svg child', () => {
+    const { node, kids } = submitNodeOf(
+      '<form><button type="submit" style="width:45px">' +
+        '<svg xmlns="http://www.w3.org/2000/svg" width="13" height="12" viewBox="0 0 13 12">' +
+        '<path d="M7.21 11.7L12.21 6.7"/></svg></button></form>',
+    )
+    expect(kids.length).toBe(1)
+    expect(kids[0]!.moduleId).toBe('base.svg')
+    expect(String(kids[0]!.props.svg)).toContain('<svg')
+    // Label keeps the childless fallback; render ignores it while children exist.
+    expect(node.props.label).toBe('Submit')
+  })
+
+  it('keeps an icon-font <i> child with its classes', () => {
+    const { kids } = submitNodeOf(
+      '<form><button type="submit"><i class="fa fa-search"></i></button></form>',
+    )
+    expect(kids.length).toBe(1)
+    expect(kids[0]!.props.customTag).toBe('i')
+    expect(kids[0]!.classIds).toContain('fa')
+    expect(kids[0]!.classIds).toContain('fa-search')
+  })
+
+  it('keeps an <img> child', () => {
+    const { kids } = submitNodeOf(
+      '<form><button type="submit"><img src="https://example.com/btn-img.svg" alt="Submit"></button></form>',
+    )
+    expect(kids.length).toBe(1)
+    expect(kids[0]!.moduleId).toBe('base.image')
+    expect(kids[0]!.props.src).toBe('https://example.com/btn-img.svg')
+  })
+
+  it('keeps the text beside an icon as a base.text child and in the label', () => {
+    const { node, kids } = submitNodeOf(
+      '<form><button type="submit">Send <i class="icon-arrow"></i></button></form>',
+    )
+    expect(kids.length).toBe(2)
+    expect(kids[0]!.moduleId).toBe('base.text')
+    expect(String(kids[0]!.props.text)).toContain('Send')
+    expect(kids[1]!.props.customTag).toBe('i')
+    expect(node.props.label).toBe('Send')
+  })
+
+  it('a text-only submit stays a leaf with its label', () => {
+    const { node, kids } = submitNodeOf('<form><button type="submit">Send</button></form>')
+    expect(kids.length).toBe(0)
+    expect(node.props.label).toBe('Send')
+  })
+
+  it('a typeless button inside a form is treated as a submit and recurses', () => {
+    const { kids } = submitNodeOf(
+      '<form><button><i class="icon-magnifier"></i></button></form>',
+    )
+    expect(kids.length).toBe(1)
+    expect(kids[0]!.props.customTag).toBe('i')
+  })
+})
+
+describe('base.submit render: children win, label is the fallback', () => {
+  const props = { ...SubmitModule.defaults, label: 'Submit', disabled: false, formId: '' }
+
+  it('renders children when present and omits the label', () => {
+    const html = SubmitModule.render!(props, ['<svg viewBox="0 0 13 12"></svg>']).html
+    expect(html).toContain('<svg viewBox="0 0 13 12"></svg>')
+    expect(html).not.toContain('>Submit<')
+    expect(html).toContain('type="submit"')
+  })
+
+  it('renders the label when there are no children', () => {
+    const html = SubmitModule.render!(props, []).html
+    expect(html).toContain('>Submit</button>')
+  })
+})
diff --git a/src/core/htmlImport/rules.ts b/src/core/htmlImport/rules.ts
index fd0f13ddd..a05c38897 100644
--- a/src/core/htmlImport/rules.ts
+++ b/src/core/htmlImport/rules.ts
@@ -461,9 +461,10 @@ export const HTML_TO_MODULE_RULES: ImportRule[] = [
   // base.button is `canHaveChildren: false` and would keep only the text.
   // Submit buttons stay on base.submit even when compound: `core/forms`
   // identifies a form's submit control by that module id, so re-tagging one as
-  // a container would leave the form without a submit. A compound submit button
-  // therefore still keeps only its label — lifting that needs base.submit to
-  // accept children, which is a module change rather than an importer one.
+  // a container would leave the form without a submit. base.submit accepts
+  // children, so a compound submit recurses too and its content (an icon-only
+  // `<svg>`, an icon-font `<i>`, an `<img>`) survives as child nodes; `label`
+  // stays as the childless fallback, the base.link contract.
   {
     match: 'button',
     map: (el) => {
@@ -494,7 +495,7 @@ export const HTML_TO_MODULE_RULES: ImportRule[] = [
         },
       }
     },
-    recurse: (el) => !isSubmitButton(el) && hasElementChild(el),
+    recurse: hasElementChild,
   },
 
   // ul / ol are BUILTIN_HTML_TAGS for base.container → container + RECURSE.
diff --git a/src/modules/base/forms/FormControls.tsx b/src/modules/base/forms/FormControls.tsx
index c8d6f25cd..6eb694b86 100644
--- a/src/modules/base/forms/FormControls.tsx
+++ b/src/modules/base/forms/FormControls.tsx
@@ -1,5 +1,6 @@
 import type { ModuleComponentProps } from '@core/module-engine'
 import { normalizeIdentifierValue } from '@core/utils/identifier'
+import { submitUsesChildren } from './content'
 
 type FormProps = Record<string, unknown> & {
   formId: string
@@ -206,8 +207,9 @@ export function RadioEditor({ mcClassName, nodeWrapperProps, props }: ModuleComp
   )
 }
 
-export function SubmitEditor({ mcClassName, nodeWrapperProps, props }: ModuleComponentProps<SubmitProps>) {
+export function SubmitEditor({ mcClassName, nodeWrapperProps, props, children }: ModuleComponentProps<SubmitProps>) {
   const formId = normalizeIdentifierValue(props.formId)
+  const childCount = Array.isArray(children) ? children.length : children != null ? 1 : 0
   return (
     <button
       {...nodeWrapperProps}
@@ -216,7 +218,7 @@ export function SubmitEditor({ mcClassName, nodeWrapperProps, props }: ModuleCom
       disabled={props.disabled}
       form={formId || undefined}
     >
-      {props.label}
+      {submitUsesChildren(childCount) ? children : props.label}
     </button>
   )
 }
diff --git a/src/modules/base/forms/content.ts b/src/modules/base/forms/content.ts
new file mode 100644
index 000000000..758a7b3a0
--- /dev/null
+++ b/src/modules/base/forms/content.ts
@@ -0,0 +1,24 @@
+/**
+ * Content-source decision for `base.submit`, shared by the publisher
+ * `render()` path (`index.ts`) and the canvas preview (`FormControls.tsx`) so
+ * the two cannot drift. Mirrors `base.link`'s `linkUsesChildren` — see
+ * `@modules/base/link/content` for why this is an explicit count check rather
+ * than a `children ?? label` short-circuit (an empty children array is not
+ * nullish).
+ *
+ * Rule: a submit button renders its children whenever it HAS children;
+ * otherwise it falls back to the `label` prop. Imported icon-only submits
+ * (an inline `<svg>` arrow, an icon-font `<i>`, an `<img>`) carry their icon
+ * as real child nodes and must not be flattened to the label text.
+ *
+ * Non-component `.ts` leaf so the editor component can import it without
+ * breaking React Fast Refresh (Constraint #309).
+ */
+
+/**
+ * Whether the submit button should render its own children (`true`) or fall
+ * back to the `label` prop (`false`), given how many rendered children it has.
+ */
+export function submitUsesChildren(childCount: number): boolean {
+  return childCount > 0
+}
diff --git a/src/modules/base/forms/index.ts b/src/modules/base/forms/index.ts
index 053f8c92a..56c8b700d 100644
--- a/src/modules/base/forms/index.ts
+++ b/src/modules/base/forms/index.ts
@@ -7,6 +7,7 @@
 import type { ModuleDefinition } from '@core/module-engine'
 import { registry } from '@core/module-engine'
 import { Type, Value, type Static } from '@core/utils/typeboxHelpers'
+import { submitUsesChildren } from './content'
 import { normalizeIdentifierValue } from '@core/utils/identifier'
 import { safeUrl } from '@modules/base/utils/escape'
 import { FORM_RUNTIME_JS } from './formRuntimeJs'
@@ -422,9 +423,12 @@ export const SubmitModule: ModuleDefinition<SubmitProps> = {
   version: '1.0.0',
   icon: SendSolidIcon,
   trusted: true,
-  canHaveChildren: false,
+  // Children carry imported icon-only submit content (an inline `<svg>`,
+  // an icon-font `<i>`, an `<img>`) as real nodes; `label` is the childless
+  // fallback. Same children-vs-text contract as base.link.
+  canHaveChildren: true,
   schema: {
-    label: { type: 'text', label: 'Label' },
+    label: { type: 'text', label: 'Label', placeholder: 'Displayed when no children' },
     disabled: { type: 'toggle', label: 'Disabled' },
     formId: { type: 'text', label: 'Form ID override', normalize: 'identifier' },
   },
@@ -432,9 +436,14 @@ export const SubmitModule: ModuleDefinition<SubmitProps> = {
   defaults: Value.Create(SubmitPropsSchema),
   component: SubmitEditor,
   htmlTag: 'button',
-  render: (props) => ({
-    html: `<button type="submit"${attrs([['form', normalizeIdentifierValue(props.formId)]])}${booleanAttrs(props, ['disabled'])}>${props.label}</button>`,
-  }),
+  render: (props, renderedChildren) => {
+    const content = submitUsesChildren(renderedChildren.length)
+      ? renderedChildren.join('')
+      : props.label
+    return {
+      html: `<button type="submit"${attrs([['form', normalizeIdentifierValue(props.formId)]])}${booleanAttrs(props, ['disabled'])}>${content}</button>`,
+    }
+  },
 }
 
 export const FormMessageModule: ModuleDefinition<FormMessageProps> = {