adp-web-components 0.3.19 → 0.3.21

package/dist/collection/templates/forms/docs-content/params.js

@@ -0,0 +1,1199 @@
+/**
+ * Props / callbacks / events / methods reference for the ticket-form components.
+ *
+ * Plain data only — no DOM, no framework, no imports. A documentation page
+ * imports this module and renders it however it likes.
+ *
+ * Every statement here was read out of the source, not out of a README:
+ *   src/components/forms/general-form.tsx
+ *   src/components/forms/general-inquiry.tsx
+ *   src/components/forms/service-booking.tsx
+ *   src/components/forms/test-drive.tsx
+ *   src/components/forms/ssc-lookup.tsx
+ *   src/components/forms/vehicle-quotation.tsx
+ *   src/features/form-hook/functions.ts      (how each callback is invoked)
+ *   src/features/form-hook/form-hook.ts      (what getForm() hands back)
+ *   src/global/lib/get-language-from-url.ts  (the language fallback)
+ *   src/components.d.ts                      (generated attribute names)
+ *
+ * Attribute names are Stencil's dash-cased form of the prop name. A prop with
+ * `attribute: null` has NO attribute at all — Stencil declares none for an
+ * object- or function-typed prop — so it can only be set from JavaScript. See
+ * the `propertyOnlyProps` export.
+ *
+ * Every URL in every example is on example.invalid on purpose. Nothing here
+ * names a real deployment, and no example carries a reCAPTCHA site key.
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers, so the five core shells can share one definition while the page only
+// ever sees fully materialised plain objects.
+// ---------------------------------------------------------------------------
+
+/** Drop entries by name. */
+const omit = (list, names) => list.filter(entry => !names.includes(entry.name));
+
+/** Shallow-merge per-name overrides, preserving order, never mutating. */
+const patch = (list, overrides) => list.map(entry => (overrides[entry.name] ? { ...entry, ...overrides[entry.name] } : { ...entry }));
+
+const CORE_TAGS = ['general-form', 'general-inquiry-form', 'service-booking-form', 'test-drive-form', 'ssc-lookup-form'];
+
+const sharesWith = tag => CORE_TAGS.filter(other => other !== tag);
+
+// ---------------------------------------------------------------------------
+// Props shared by every form shell.
+// ---------------------------------------------------------------------------
+
+const coreProps = () => [
+  {
+    name: 'language',
+    attribute: 'language',
+    type: "'en' | 'ar' | 'ku' | 'ru'",
+    required: false,
+    default: 'inferred from the page URL at componentWillLoad — see the warning',
+    summary: 'Language of the labels, validation messages and the Accept-Language request header, and the text direction of the rendered form.',
+    example: [
+      '<!-- set it. always set it. -->',
+      '<general-form language="en"></general-form>',
+      '',
+      '<script>',
+      "  // language IS reactive - every shell has a @Watch('language').",
+      '  // Reassigning it reloads the locale and re-renders every field in place.',
+      "  document.querySelector('general-form').language = 'ar';",
+      '</script>',
+    ].join('\n'),
+    warning: [
+      'Omitting this is not "default to English". componentWillLoad falls back to',
+      'getLanguageFromUrl(), which resolves in this order:',
+      '  1. ?lang= / ?lng= / ?language= on the current URL, lower-cased and matched',
+      '     against en|english|ar|arabic|ku|ckb|kurdish|sorani|ru|russian;',
+      '  2. otherwise location.pathname.toLowerCase().includes("/" + key) for each of',
+      '     those same keys, in that order - a SUBSTRING test, not a path-segment test;',
+      '  3. otherwise "en".',
+      'So /parts/archive contains "/ar" and renders the form in Arabic, right-to-left, on',
+      'an English page. /products/runway contains "/ru" and renders Russian. Setting',
+      'language explicitly is effectively mandatory. The prop is reflect: true, so the',
+      'inferred value is written back onto the element as an attribute.',
+    ].join('\n'),
+  },
+  {
+    name: 'structure',
+    attribute: null,
+    type: 'FormElementStructure<any> | undefined',
+    required: true,
+    default: 'undefined',
+    summary: 'The whole form definition: which fields render, in what order, with what copy, and where the submit goes. Supply this, or gistId, or structureUrl.',
+    example: [
+      "const form = document.querySelector('general-form');",
+      '',
+      '// PROPERTY assignment. There is no structure="" attribute.',
+      'form.structure = {',
+      '  data: {',
+      "    requestUrl: 'https://api.example.invalid/tickets',",
+      "    requestMethod: 'POST',",
+      "    brandId: 'demo-brand',",
+      "    theme: 'docs-preset',",
+      "    localization: { en: { submit: 'Send' }, ar: { submit: 'ارسال' } },",
+      '  },',
+      '  requiredContext: { name: true, email: true, message: true },',
+      "  tag: 'div',",
+      "  id: 'container',",
+      "  children: [{ name: 'name' }, { name: 'email' }, { name: 'message' }, { name: 'submit' }],",
+      '};',
+    ].join('\n'),
+    warning: [
+      'Two separate traps.',
+      '',
+      '1. No attribute. structure is a mutable object prop, so Stencil generates no',
+      '   attribute for it. <general-form structure="..."> does nothing at all.',
+      '',
+      '2. Not reactive. There is no @Watch("structure") on ANY form shell - grep the repo:',
+      '   the only watches are @Watch("language") and @Watch("structureRendered"). The',
+      '   structure is consumed once, inside componentDidLoad. Assigning .structure after',
+      '   the element has mounted changes the property and nothing else: the already-built',
+      '   FormHook, the rendered fields, the validation schema and the request URL all keep',
+      '   the old definition. To swap a structure you must remove the element and create a',
+      '   fresh one.',
+    ].join('\n'),
+  },
+  {
+    name: 'fields',
+    attribute: null,
+    type: 'object | undefined   //  Record<fieldName, extraProps>',
+    required: false,
+    default: 'undefined (the inner form-structure falls back to {})',
+    summary:
+      'Per-field prop overrides, merged into the props of the element with the matching name — the escape hatch for anything the JSON structure cannot express, such as a function.',
+    example: [
+      "const form = document.querySelector('service-booking-form');",
+      '',
+      'form.fields = {',
+      '  // keys are field names from the structure; values are props for that element',
+      "  name: { localization: { en: { label: 'Your full name' } } },",
+      "  phone: { isDisabled: true, staticValue: '+100000000' },",
+      '  // a formatter is a function, so this is the only way it can arrive',
+      '  vin: { formatter: value => value.toUpperCase() },',
+      '};',
+    ].join('\n'),
+    warning: [
+      'Property only - no attribute, same as structure. It is read on every render of the',
+      'inner form-structure rather than once, but it has no watcher, so assign a NEW object',
+      '(form.fields = { ...form.fields, phone: {...} }) rather than mutating the existing',
+      'one, and expect the repaint to come from whatever else triggered a render - a',
+      'language change, or (await el.getForm()).rerender({ rerenderAll: true }).',
+    ].join('\n'),
+  },
+  {
+    name: 'gistId',
+    attribute: 'gist-id',
+    type: 'string | undefined',
+    required: false,
+    default: 'undefined',
+    summary: 'Id of a public GitHub gist whose first .json file is fetched and used as the structure. Convenient for iterating on a structure with no deploy.',
+    example: ['<general-form', '  language="en"', '  gist-id="0f1e2d3c4b5a69788796a5b4c3d2e1f0"', '></general-form>'].join('\n'),
+    warning: [
+      'Only consulted when structure is still unset at componentDidLoad, and it beats',
+      'structureUrl - the code tries gistId first and only falls through to structureUrl',
+      'when gistId is absent. The fetch goes to api.github.com, which is rate limited for',
+      'unauthenticated callers, and on any failure gistLoader logs and returns undefined,',
+      'leaving the form with no structure at all. Fine for a demo; not a delivery mechanism.',
+    ].join('\n'),
+  },
+  {
+    name: 'structureUrl',
+    attribute: 'structure-url',
+    type: 'string | undefined',
+    required: false,
+    default: 'undefined',
+    summary: 'URL of a JSON document to fetch and use as the structure.',
+    example: ['<test-drive-form', '  language="en"', '  structure-url="https://cdn.example.invalid/forms/test-drive.json"', '></test-drive-form>'].join('\n'),
+    warning: [
+      'Only consulted when structure is unset AND gistId is unset. The fetch happens in',
+      'componentDidLoad, so the form shows its loader until it lands. Like structure, it is',
+      'read once - changing the attribute afterwards reloads nothing.',
+    ].join('\n'),
+  },
+  {
+    name: 'theme',
+    attribute: 'theme',
+    type: 'string | undefined',
+    required: false,
+    default: 'undefined',
+    summary: 'Extra token appended to the shell part list, so a page can target one instance with ::part().',
+    example: [
+      '<general-form theme="compact" class="docs-form"></general-form>',
+      '',
+      '<style>',
+      '  /* the shell renders part="shift-form <structure.data.theme> <theme>" */',
+      '  general-form::part(shift-form) { display: flex; flex-direction: column; }',
+      '  general-form::part(compact) { max-width: 480px; gap: 12px; }',
+      '</style>',
+    ].join('\n'),
+    warning: [
+      'It does not replace structure.data.theme - both tokens land in the same part=',
+      'attribute, via cn("shift-form", structure?.data?.theme, theme), so both selectors',
+      'match at once. ::part() is the entire theming surface: the components expose no CSS',
+      'custom properties, and an element without its own part= cannot be reached at all.',
+      'Panels that shift-portal moves to <body> escape tag::part() - target them through a',
+      'class on the host instead (.my-form::part(...)).',
+      'NOT AVAILABLE on vehicle-quotation-form.',
+    ].join('\n'),
+  },
+  {
+    name: 'formId',
+    attribute: 'form-id',
+    type: 'string | undefined',
+    required: false,
+    default: 'undefined',
+    summary: 'Value written to the id attribute of the inner <form> element inside the shadow root.',
+    example: [
+      '<general-form form-id="contact-form"></general-form>',
+      '',
+      '<script>',
+      '  // the id lives INSIDE the shadow root, so reach it through shadowRoot',
+      "  const host = document.querySelector('general-form');",
+      "  const innerForm = host.shadowRoot.getElementById('contact-form');",
+      '</script>',
+    ].join('\n'),
+    warning: [
+      'Shadow DOM scopes ids. An outside <button form="contact-form"> will NOT associate',
+      'with it. This is a hook for analytics and automation that already walk the shadow',
+      "root - to submit from outside, call the element's submit() method instead.",
+    ].join('\n'),
+  },
+  {
+    name: 'isDev',
+    attribute: 'is-dev',
+    type: 'boolean',
+    required: false,
+    default: 'false',
+    summary: 'Rewrites the literal text production=true to production=false in the resolved request URL, immediately before the fetch.',
+    example: [
+      "<!-- structure.data.requestUrl = 'https://api.example.invalid/tickets?production=true' -->",
+      '',
+      '<general-form is-dev="true" language="en"></general-form>',
+      '',
+      '<!-- the submit POSTs to https://api.example.invalid/tickets?production=false -->',
+    ].join('\n'),
+    warning: [
+      'This is a string substitution and nothing more:',
+      '  requestEndpoint = requestEndpoint.replaceAll("production=true", "production=false")',
+      'It has NOTHING to do with mocks, fixtures or the dev server. It does not switch the',
+      'structure source, does not relax validation, and does not change reCAPTCHA. If the',
+      'endpoint does not contain that exact lower-case literal, is-dev does literally',
+      'nothing. It rewrites EVERY occurrence, anywhere in the URL, and it runs after the',
+      'endpoint has been chosen, so it applies to the mobile endpoints too.',
+    ].join('\n'),
+  },
+  {
+    name: 'disableScrollToTop',
+    attribute: 'disable-scroll-to-top',
+    type: 'boolean | undefined',
+    required: false,
+    default: 'undefined (falsy - scrolling is ON)',
+    summary: 'Suppresses the automatic smooth scroll to the top of the form that follows a successful submit.',
+    example: ['<!-- the form sits in a modal; moving the page underneath it looks broken -->', '<service-booking-form disable-scroll-to-top="true"></service-booking-form>'].join(
+      '\n',
+    ),
+    warning: [
+      "The default scroll targets the host element's first shadow child, offsets it by",
+      '-100px and calls window.scrollTo({ behavior: "smooth" }). It runs on success',
+      'REGARDLESS of what successCallback returned - suppressing the built-in dialog does',
+      'not suppress the scroll. This prop is the only way to stop it.',
+    ].join('\n'),
+  },
+  {
+    name: 'isMobileForm',
+    attribute: 'is-mobile-form',
+    type: 'boolean',
+    required: false,
+    default: 'false',
+    summary: 'Switches the submit from reCAPTCHA + requestUrl to a caller-supplied token + one of the app endpoints. For embedding the form inside a native app webview.',
+    example: [
+      '<general-form id="embedded" is-mobile-form="true"></general-form>',
+      '',
+      '<script>',
+      "  const el = document.getElementById('embedded');",
+      '',
+      '  // required whenever mobile mode is on',
+      '  el.getMobileToken = async () => window.NativeBridge.getToken();',
+      '',
+      '  // structure.data must carry the matching endpoints:',
+      "  //   requestAppUrl      - used when the token starts with 'bearer'",
+      '  //   requestAppCheckUrl - used for any other token',
+      '</script>',
+    ].join('\n'),
+    warning: [
+      'structure.data.isMobileForm BEATS this prop whenever the KEY EXISTS, including when',
+      'its value is false:',
+      '  Object.hasOwn(structure?.data ?? {}, "isMobileForm") ? !!structure.data.isMobileForm : prop',
+      'That is a presence check, not a truthiness check, so "isMobileForm": false in the',
+      'structure disables mobile mode even with is-mobile-form="true" on the tag. Turning',
+      'it on also skips injecting the reCAPTCHA script at load.',
+    ].join('\n'),
+  },
+  {
+    name: 'extraPayload',
+    attribute: null,
+    type: 'object',
+    required: false,
+    default: 'undefined',
+    summary: 'Extra key/value pairs merged into the JSON request body on submit.',
+    example: [
+      "const form = document.querySelector('general-inquiry-form');",
+      '',
+      '// property assignment - object props get no attribute',
+      "form.extraPayload = { sourcePage: location.pathname, campaign: 'docs-demo' };",
+    ].join('\n'),
+    warning: [
+      'Precedence runs OPPOSITE to extraHeader. functions.ts merges',
+      '  structure.data.extraPayload first, then the extraPayload PROP,',
+      'so on a key collision the PROP WINS for the payload. Marketing/UTM values merge',
+      'after both. Declared but never read by vehicle-quotation-form.',
+    ].join('\n'),
+  },
+  {
+    name: 'extraHeader',
+    attribute: null,
+    type: 'object',
+    required: false,
+    default: 'undefined',
+    summary: 'Extra request headers merged on top of the built-in Content-Type / Brand / Accept-Language set.',
+    example: ["const form = document.querySelector('general-inquiry-form');", '', "form.extraHeader = { 'X-Source': 'docs-demo', 'X-Tenant': 'demo' };"].join('\n'),
+    warning: [
+      'Precedence runs OPPOSITE to extraPayload. functions.ts merges',
+      '  the extraHeader PROP first, then structure.data.extraHeader,',
+      'so on a key collision the STRUCTURE WINS for headers. Recaptcha-Token, Authorization',
+      'and verification-token are set after this merge and cannot be overridden from here.',
+      'Declared but never read by vehicle-quotation-form.',
+    ].join('\n'),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Callbacks shared by every form shell. All are function-valued props, so none
+// of them has an attribute — they must be assigned in JavaScript.
+// ---------------------------------------------------------------------------
+
+const coreCallbacks = () => [
+  {
+    name: 'successCallback',
+    signature: '(data: any, message?: string) => boolean | void | Promise<boolean | void>',
+    calledWhen:
+      'The submit response came back with response.ok. `data` is the parsed JSON body (or {} if the body would not parse); `message` is the localized "Form submitted successfully." string for the active language.',
+    mustReturn: 'true — or any truthy value. The result is coerced with `!!(await successCallback(...))`; if that is false the built-in success dialog is NOT opened.',
+    summary: 'Runs after a successful submit, and decides whether the built-in success dialog still appears.',
+    example: [
+      "const form = document.querySelector('general-form');",
+      '',
+      'form.successCallback = async (data, message) => {',
+      "  window.dataLayer?.push({ event: 'ticket_submitted', ticketId: data?.id });",
+      '',
+      '  // RETURN TRUE to keep the built-in dialog.',
+      '  return true;',
+      '};',
+      '',
+      '// ...or take over the confirmation UI completely:',
+      'form.successCallback = async data => {',
+      '  showMyOwnThankYouPanel(data);',
+      '  return false; // suppress the built-in dialog on purpose',
+      '};',
+    ].join('\n'),
+    warning: [
+      'The exact rule in functions.ts:',
+      '  let openDefaultDialog = true;',
+      '  if (successCallback) openDefaultDialog = !!(await successCallback(data, message));',
+      '  if (openDefaultDialog) form.openDialog();',
+      'So a handler with no return statement returns undefined, !!undefined is false, and',
+      'the user is shown NOTHING - the form silently resets and scrolls. Same for an async',
+      'handler that resolves to nothing, since the value is awaited first. If you attach a',
+      'successCallback at all, end it with `return true;` unless you are deliberately',
+      'replacing the dialog.',
+      'The post-success reset, re-render and scroll-to-top run either way.',
+    ].join('\n'),
+  },
+  {
+    name: 'errorCallback',
+    signature: '(error: any, message: string) => boolean | void | Promise<boolean | void>',
+    calledWhen:
+      'The submit threw or the response was not ok. `error` is the caught value; `message` is error.message || error.Message?.Body || error.message?.body || the localized wildcard error, or "".',
+    mustReturn: 'true — or any truthy value. The result is coerced with `!!(await errorCallback(...))`; if that is false the built-in error dialog does NOT open.',
+    summary: 'Runs on a failed submit, and decides whether the built-in error dialog still opens.',
+    example: [
+      "const form = document.querySelector('test-drive-form');",
+      '',
+      'form.errorCallback = async (error, message) => {',
+      "  reportToMyLogger('form-submit-failed', { message });",
+      '',
+      '  // RETURN TRUE to keep the built-in error dialog.',
+      '  return true;',
+      '};',
+    ].join('\n'),
+    warning: [
+      'Same truthiness rule as successCallback, and the same trap:',
+      '  let openDefaultDialog = true;',
+      '  if (errorCallback) openDefaultDialog = !!(await errorCallback(error, message));',
+      '  if (openDefaultDialog) context.errorMessage = message;',
+      'Returning undefined suppresses the only feedback the user would have got. Note the',
+      'error is also console.error-ed by functions.ts before this runs, so the browser',
+      'console will show it even when the UI does not.',
+    ].join('\n'),
+  },
+  {
+    name: 'loadingChanges',
+    signature: '(loading: boolean) => void',
+    calledWhen: 'Every time the internal loading flag flips — true as a submit begins, false in the finally block once it has settled (success or failure).',
+    mustReturn: 'nothing — the return value is ignored.',
+    summary: 'Mirrors the form busy state outward, so surrounding page chrome can disable itself while a submit is in flight.',
+    example: [
+      "const form = document.querySelector('service-booking-form');",
+      "const pageSubmit = document.getElementById('page-cta');",
+      '',
+      'form.loadingChanges = loading => {',
+      '  pageSubmit.disabled = loading;',
+      "  document.body.classList.toggle('is-submitting', loading);",
+      '};',
+    ].join('\n'),
+    warning:
+      'It is a notification, not a control: returning false does not cancel anything, and the form renders its own loader regardless. It fires before successCallback / errorCallback for the true edge and after them for the false edge.',
+  },
+  {
+    name: 'formReadyCallback',
+    signature: '() => void',
+    calledWhen: 'Once, from @Watch("structureRendered"), about 300 ms after the inner form-structure finishes its first componentDidLoad.',
+    mustReturn: 'nothing — the return value is ignored.',
+    summary: 'The earliest point at which the form is really usable: the structure is resolved, the FormHook exists, and the fields are in the DOM.',
+    example: [
+      "const form = document.querySelector('general-form');",
+      '',
+      'form.formReadyCallback = async () => {',
+      '  const hook = await form.getForm(); // guaranteed to resolve to a hook here',
+      "  hook.setCachedValues({ campaign: 'docs-demo' });",
+      "  document.getElementById('page-cta').disabled = false;",
+      '};',
+    ].join('\n'),
+    warning: [
+      'Fires exactly once per element. structureRendered goes false -> true and never back,',
+      'so it does NOT fire again on a language change, a re-render, or a post-submit reset.',
+      'It must be assigned before the element mounts (or in the same tick) - assigning it',
+      'after the 300 ms has already elapsed means it never runs.',
+    ].join('\n'),
+  },
+  {
+    name: 'stepChangeCallback',
+    signature: '(step: number, currentForm?: any) => void',
+    calledWhen: 'NEVER. This prop is declared but is not invoked anywhere in the codebase.',
+    mustReturn: 'n/a — it is never called.',
+    summary: 'NON-FUNCTIONAL. Declared on the five core shells and present in the generated types, but dead: nothing calls it.',
+    example: [
+      '// This does nothing. It is documented so nobody spends an afternoon on it.',
+      "document.querySelector('general-form').stepChangeCallback = step => console.log(step);",
+      '',
+      '// The supported way to read the current step of a multi-step form:',
+      "const hook = await document.querySelector('general-form').getForm();",
+      'const step = hook.formStructure?.currentStep; // 1-based',
+      '',
+      '// ...and the supported way to MOVE between steps:',
+      'hook.updateStep(2);',
+    ].join('\n'),
+    warning: [
+      'Verified by grep over src/: the identifier appears only as the five @Prop',
+      'declarations, the field on FormHookInterface, and the generated entries in',
+      'components.d.ts. There is no call site. There is currently NO notification of a step',
+      'change - poll hook.formStructure?.currentStep, or wrap hook.updateStep yourself.',
+      'Not declared at all on vehicle-quotation-form.',
+    ].join('\n'),
+  },
+  {
+    name: 'getMobileToken',
+    signature: '() => string | Promise<string>',
+    calledWhen: 'On submit, only when the resolved mobile mode is on (structure.data.isMobileForm if that key exists, otherwise the isMobileForm prop). The result is awaited.',
+    mustReturn:
+      'a non-empty string. If it starts with "bearer" (case-insensitive) it is sent as the Authorization header and the request goes to structure.data.requestAppUrl; any other value is sent as the verification-token header and the request goes to structure.data.requestAppCheckUrl.',
+    summary: 'Supplies the auth token that replaces reCAPTCHA when the form is embedded in a native app webview.',
+    example: [
+      "const form = document.querySelector('general-form');",
+      'form.isMobileForm = true;',
+      '',
+      '// Bearer branch -> Authorization header -> structure.data.requestAppUrl',
+      "form.getMobileToken = async () => 'Bearer ' + (await window.NativeBridge.accessToken());",
+      '',
+      '// App-check branch -> verification-token header -> structure.data.requestAppCheckUrl',
+      'form.getMobileToken = async () => window.NativeBridge.appCheckToken();',
+    ].join('\n'),
+    warning: [
+      'REQUIRED whenever mobile mode is on. The call is unguarded -',
+      '  const token = await context.getMobileToken();',
+      '  if (token.toLowerCase().startsWith("bearer")) ...',
+      '- so leaving it unset, or resolving to undefined/null, throws a TypeError that lands',
+      'in the submit catch and surfaces to the user as a generic submit failure. It is not',
+      'consulted at all when mobile mode is off.',
+    ].join('\n'),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Methods. Both are @Method(), so both are async and both are only callable
+// once the custom element has been upgraded (await customElements.whenDefined).
+// ---------------------------------------------------------------------------
+
+const coreMethods = () => [
+  {
+    name: 'getForm',
+    signature: 'getForm(): Promise<FormHook<any> | undefined>',
+    summary: 'Resolves with the internal FormHook — the imperative handle for reading values, reading errors, resetting, re-rendering and moving between steps.',
+    example: [
+      "const el = document.querySelector('general-form');",
+      "await customElements.whenDefined('general-form');",
+      '',
+      'const hook = await el.getForm();',
+      '',
+      'hook.getValues();                       // current values as a plain object',
+      "hook.getValue('email');                 // one value",
+      'hook.getFormErrors();                   // { fieldName: message }',
+      "hook.setCachedValues({ source: 'docs' });// values merged in at submit time",
+      "hook.validateInput('email');            // re-run validation for one field",
+      'hook.reset();                           // clear every field, back to step 1',
+      'hook.updateStep(2);                     // multi-step navigation (1-based)',
+      'hook.rerender({ rerenderAll: true });   // force every field to repaint',
+      "hook.addWatcher('email', ({ values }) => console.log(values.email));",
+      'hook.submit();                          // same as el.submit()',
+    ].join('\n'),
+  },
+  {
+    name: 'submit',
+    signature: 'submit(): Promise<void>',
+    summary: 'Triggers the same submit path as the built-in submit button: validation, then the request. A no-op if the hook has not been built yet.',
+    example: [
+      "const el = document.querySelector('general-form');",
+      '',
+      '// submit from a button that lives outside the shadow root',
+      "document.getElementById('page-cta').addEventListener('click', () => el.submit());",
+    ].join('\n'),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// The components.
+// ---------------------------------------------------------------------------
+
+export const components = [
+  {
+    tag: 'general-form',
+    summary:
+      'The plain ticket form. Everything it renders comes from the structure — it adds no fields of its own and no submit middleware, so it is the right starting point for any new form.',
+    sharesCoreWith: sharesWith('general-form'),
+    differsBy: 'Nothing. It is the unmodified shared shell: the default validation schema, the default element mapper, and functionHooks.onFormSubmit with no middleware.',
+    props: coreProps(),
+    callbacks: coreCallbacks(),
+    events: [],
+    methods: coreMethods(),
+  },
+  {
+    tag: 'general-inquiry-form',
+    summary: 'general-form plus a built-in `generalTicketType` select, for routing an inquiry to a category.',
+    sharesCoreWith: sharesWith('general-inquiry-form'),
+    differsBy: [
+      'Adds one element to the mapper and one rule to the schema, both named generalTicketType:',
+      '  * the element renders a clearable <form-select> whose options come from the',
+      '    structure node itself (props.options), each option being',
+      '    { value, en, ar, ku, ru } and labelled in the active language;',
+      '  * the rule makes it required only when requiredContext.generalTicketType is true.',
+      'The submit path, the props and the callbacks are identical to general-form.',
+    ].join('\n'),
+    props: coreProps(),
+    callbacks: coreCallbacks(),
+    events: [],
+    methods: coreMethods(),
+  },
+  {
+    tag: 'service-booking-form',
+    summary: 'The shared shell aimed at service bookings — branch, date and slot pickers all come from the structure and the shared element mapper.',
+    sharesCoreWith: sharesWith('service-booking-form'),
+    differsBy:
+      'Nothing in code: same validation, same mapper, same submit path as general-form. It is a separate tag so a page can style and address a booking form independently, and so the structures for it can live apart from the inquiry ones.',
+    props: coreProps(),
+    callbacks: coreCallbacks(),
+    events: [],
+    methods: coreMethods(),
+  },
+  {
+    tag: 'test-drive-form',
+    summary: 'The shared shell aimed at test-drive requests.',
+    sharesCoreWith: sharesWith('test-drive-form'),
+    differsBy: 'Nothing in code: same validation, same mapper, same submit path as general-form. Separate tag for separate styling, structures and analytics.',
+    props: coreProps(),
+    callbacks: coreCallbacks(),
+    events: [],
+    methods: coreMethods(),
+  },
+  {
+    tag: 'ssc-lookup-form',
+    summary: 'The shared shell with a submit middleware that turns the form values into a GET-style lookup by VIN instead of a JSON body.',
+    sharesCoreWith: sharesWith('ssc-lookup-form'),
+    differsBy: [
+      'The only difference is a submit middleware, applied after the payload and headers',
+      'have been built and before the request:',
+      '  * the request URL has the literal ${vin} replaced with the uppercased vin value,',
+      '    so structure.data.requestUrl is expected to contain that placeholder;',
+      '  * the name and phone values move OUT of the body and into the Customer-Name and',
+      '    Customer-Phone headers, URI-encoded;',
+      '  * the body is emptied - payload becomes {}.',
+      'Consequence: extraPayload is built and then thrown away by the middleware, so it',
+      'cannot reach the server here. Use extraHeader instead. Props, callbacks and methods',
+      'are otherwise identical to general-form.',
+    ].join('\n'),
+    props: patch(coreProps(), {
+      extraPayload: {
+        warning: [
+          'On ssc-lookup-form this prop is INERT. The submit middleware replaces the whole',
+          'payload with {} after the merge has happened, so nothing you put here is sent.',
+          'Put the value in extraHeader, or in the URL through structure.data.requestUrl.',
+        ].join('\n'),
+      },
+      structure: {
+        example: [
+          "const form = document.querySelector('ssc-lookup-form');",
+          '',
+          'form.structure = {',
+          '  data: {',
+          '    // ${vin} is substituted with the uppercased vin field at submit time',
+          "    requestUrl: 'https://api.example.invalid/campaigns/${vin}',",
+          "    requestMethod: 'GET',",
+          '  },',
+          '  requiredContext: { vin: true, name: true, phone: true },',
+          "  tag: 'div',",
+          "  children: [{ name: 'vin' }, { name: 'name' }, { name: 'phone' }, { name: 'submit' }],",
+          '};',
+        ].join('\n'),
+      },
+    }),
+    callbacks: coreCallbacks(),
+    events: [],
+    methods: coreMethods(),
+  },
+  {
+    tag: 'vehicle-quotation-form',
+    summary:
+      'A different animal. It has its own element mapper, its own validation schema and its own hand-written submit — it does NOT go through the shared functionHooks.onFormSubmit — so several shared props are declared but never read.',
+    sharesCoreWith: [],
+    differsBy: [
+      'Keep this one separate on the page. It shares the shell and the lifecycle helpers,',
+      'but not the submit.',
+      '',
+      'MISSING props/callbacks that the five core shells have:',
+      '  * theme            - not declared; the shell part is hard-coded to',
+      '                       "shift-form vehicle-quotation-<structure.data.theme>",',
+      '                       so the only theming hook is structure.data.theme.',
+      '  * stepChangeCallback - not declared at all (it is dead on the others anyway).',
+      '',
+      'DECLARED BUT IGNORED - these exist on the element and in the generated types, and',
+      'the hand-written submit never reads them:',
+      '  * extraHeader  - headers are built inline as Brand / Accept-Language /',
+      '                   Content-Type only.',
+      '  * extraPayload - only structure.data.extraPayload is merged; the PROP is dropped.',
+      '',
+      'OTHER submit-path differences:',
+      '  * the payload is MAPPED, not passed through: name, phone,',
+      '    companyBranchId (from the dealer field), cityId, vehicleQuotationType (from',
+      '    structure.data.quotationType), preferredContactTime (default "NotSpecified"),',
+      '    preferredPaymentMethod (default "Flexible"), vehicle, and either',
+      '    currentOrTradeInVehicle or an additionalData block depending on',
+      '    structure.data.nameContactedVehicles;',
+      '  * the method is always POST - structure.data.requestMethod is ignored;',
+      '  * structure.data.truncatedFields is ignored;',
+      '  * marketing/UTM values are always merged into the payload, never into headers;',
+      '  * structure.data.pushAnalyticsEventTo, if set, names a window array that receives',
+      '    a { event: "get_a_quote", ... } push after a successful submit.',
+      '',
+      'The props, callbacks and methods listed below are the ones this component actually',
+      'has; the warnings mark the inert ones.',
+    ].join('\n'),
+    props: patch(omit(coreProps(), ['theme']), {
+      structure: {
+        type: 'FormElementStructure<vehicleQuotationElementNames> | undefined',
+        summary:
+          'The form definition. Field names are constrained to this component\'s own mapper: submit, name, phone, vehicle, dealer, city, paymentType, contactTime, ownVehicle, currentVehicleBrand, currentVehicleModel, vehicleImage, and the heading nodes choose / "current car" / "contact information".',
+        example: [
+          "const form = document.querySelector('vehicle-quotation-form');",
+          '',
+          'form.structure = {',
+          '  data: {',
+          "    requestUrl: 'https://api.example.invalid/quotations',",
+          "    brandId: 'demo-brand',",
+          "    quotationType: 'NewVehicle',",
+          '    theme: \'light\',            // becomes part="vehicle-quotation-light"',
+          '    nameContactedVehicles: true,',
+          "    pushAnalyticsEventTo: 'dataLayer',",
+          '    // recaptchaKey is REQUIRED here unless mobile mode is on - see the warning',
+          '  },',
+          '  requiredContext: { name: true, phone: true, vehicle: true, dealer: true },',
+          "  tag: 'div',",
+          "  children: [{ name: 'vehicle' }, { name: 'dealer' }, { name: 'name' }, { name: 'phone' }, { name: 'submit' }],",
+          '};',
+        ].join('\n'),
+        warning: [
+          'Same two traps as everywhere else - property only, and no @Watch("structure"), so',
+          'reassigning it after mount does nothing.',
+          '',
+          'Extra trap here: this component resolves mobile mode with a bare',
+          '  Object.hasOwn(this.structure?.data, "isMobileForm")',
+          'with the shared guard in place, so a structure with no data object is handled',
+          'the submit. The shared shells guard that case; this one does not.',
+        ].join('\n'),
+      },
+      extraHeader: {
+        warning: [
+          'INERT on vehicle-quotation-form. The prop is declared, and the generated types',
+          'advertise it, but the hand-written submit builds its headers inline and never',
+          'reads it. There is no structure-level substitute either.',
+        ].join('\n'),
+      },
+      extraPayload: {
+        warning: [
+          'INERT on vehicle-quotation-form. Only structure.data.extraPayload is merged into',
+          'the body; the PROP is never read. Put the values in structure.data.extraPayload.',
+        ].join('\n'),
+      },
+      isMobileForm: {
+        warning: [
+          'Same presence-not-truthiness rule as the shared shells, but implemented inline',
+          'using the same shared helper:',
+          '  Object.hasOwn(this.structure?.data, "isMobileForm") ? ... : this.isMobileForm',
+          'so a structure with no data object throws on submit.',
+          '',
+          'Also: when mobile mode is OFF this component calls',
+          '  grecaptcha.execute(structure.data.recaptchaKey, ...)',
+          'UNCONDITIONALLY - the shared shells only do that when a key is present. A browser',
+          'structure with no recaptchaKey therefore fails at submit rather than posting.',
+        ].join('\n'),
+      },
+    }),
+    callbacks: omit(coreCallbacks(), ['stepChangeCallback']),
+    events: [],
+    methods: coreMethods(),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Props that have no attribute at all.
+// ---------------------------------------------------------------------------
+
+export const propertyOnlyProps = [
+  {
+    name: 'structure',
+    why: 'A mutable object prop. Stencil only generates an attribute for string, number and boolean props, so there is no structure="" to write — and an HTML attribute could not carry an object anyway.',
+    example: ["document.querySelector('general-form').structure = { data: { requestUrl: 'https://api.example.invalid/tickets' }, tag: 'div', children: [] };"].join('\n'),
+  },
+  {
+    name: 'fields',
+    why: 'A mutable object prop, same reason as structure. It also carries functions (formatter, iconAction), which no attribute could serialise.',
+    example: ["document.querySelector('general-form').fields = { vin: { formatter: v => v.toUpperCase() } };"].join('\n'),
+  },
+  {
+    name: 'extraPayload',
+    why: 'Object-typed prop — no attribute is generated.',
+    example: ["document.querySelector('general-form').extraPayload = { sourcePage: location.pathname };"].join('\n'),
+  },
+  {
+    name: 'extraHeader',
+    why: 'Object-typed prop — no attribute is generated.',
+    example: ["document.querySelector('general-form').extraHeader = { 'X-Source': 'docs-demo' };"].join('\n'),
+  },
+  {
+    name: 'successCallback',
+    why: 'Function-typed prop. No attribute exists; an onsuccess="" style attribute would not work either, because this is not a DOM event.',
+    example: ["document.querySelector('general-form').successCallback = async () => true;"].join('\n'),
+  },
+  {
+    name: 'errorCallback',
+    why: 'Function-typed prop — same as successCallback.',
+    example: ["document.querySelector('general-form').errorCallback = async () => true;"].join('\n'),
+  },
+  {
+    name: 'loadingChanges',
+    why: 'Function-typed prop.',
+    example: ["document.querySelector('general-form').loadingChanges = busy => console.log('busy:', busy);"].join('\n'),
+  },
+  {
+    name: 'formReadyCallback',
+    why: 'Function-typed prop. Assign it before the element mounts, or it may never fire.',
+    example: ["document.querySelector('general-form').formReadyCallback = () => console.log('ready');"].join('\n'),
+  },
+  {
+    name: 'stepChangeCallback',
+    why: 'Function-typed prop. Property-only AND never invoked — see the gotcha.',
+    example: ['// no attribute, and no effect either', "document.querySelector('general-form').stepChangeCallback = () => {};"].join('\n'),
+  },
+  {
+    name: 'getMobileToken',
+    why: 'Function-typed prop. Required when mobile mode is on, and there is no attribute form of it, so a mobile-mode form can never be configured from markup alone.',
+    example: ["document.querySelector('general-form').getMobileToken = async () => 'Bearer ' + (await window.NativeBridge.accessToken());"].join('\n'),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Gotchas — the things that cost an afternoon.
+// ---------------------------------------------------------------------------
+
+export const gotchas = [
+  {
+    id: 'structure-is-not-reactive',
+    title: 'Reassigning .structure after mount does nothing. Destroy and re-create the element.',
+    detail: [
+      'There is no @Watch("structure") on any form shell. The only watches in',
+      'src/components/forms are @Watch("language") and @Watch("structureRendered").',
+      'The structure is read once, in componentDidLoad, to build the FormHook, the',
+      'validation schema and the rendered fields. Setting .structure afterwards updates the',
+      'property, and the shell re-renders, but the hook and the fields it already built are',
+      'not rebuilt from it - so a "new" structure produces a form that is still the old one',
+      'except for whatever the render reads directly (the part list, and the structure the',
+      'inner form-structure walks, which will now disagree with the schema it validates',
+      'against).',
+      '',
+      'The only supported way to change a structure at runtime is to replace the element.',
+    ].join('\n'),
+    example: [
+      '// WRONG - looks like it works, then behaves like the old form',
+      "const el = document.querySelector('general-form');",
+      'el.structure = nextStructure;',
+      '',
+      '// RIGHT - throw the element away and build a fresh one',
+      'function mountForm(structure, language) {',
+      "  const host = document.getElementById('form-slot');",
+      '  host.replaceChildren();                       // drops the old element entirely',
+      '',
+      "  const el = document.createElement('general-form');",
+      '  el.language = language;',
+      '  el.structure = structure;                     // set BEFORE it is connected',
+      '  el.successCallback = async () => true;',
+      '  host.appendChild(el);                         // componentDidLoad reads it here',
+      '  return el;',
+      '}',
+    ].join('\n'),
+  },
+  {
+    id: 'callbacks-must-return-true',
+    title: 'successCallback and errorCallback must return true, or the user is shown nothing.',
+    detail: [
+      'Both handlers gate the built-in feedback on the truthiness of their own return value:',
+      '',
+      '  // formSuccessHandler',
+      '  let openDefaultDialog = true;',
+      '  if (successCallback) openDefaultDialog = !!(await successCallback(data, message));',
+      '  if (openDefaultDialog) form.openDialog();',
+      '',
+      '  // formErrorHandler',
+      '  let openDefaultDialog = true;',
+      '  if (errorCallback) openDefaultDialog = !!(await errorCallback(error, message));',
+      '  if (openDefaultDialog) context.errorMessage = message;',
+      '',
+      'The flag starts as true, so a form with NO callback always shows its dialog or its',
+      'error. The moment you attach a callback, the callback owns the decision. Anything',
+      'falsy suppresses it - and a function with no return statement returns undefined,',
+      'which is falsy. The value is awaited first, so an async handler that resolves to',
+      'nothing behaves identically.',
+      '',
+      'This is the single most common way to end up with a form that submits successfully',
+      'and appears to do nothing.',
+    ].join('\n'),
+    example: [
+      '// SILENT: the submit works, the form resets, the user sees no confirmation',
+      'form.successCallback = async data => {',
+      '  track(data);',
+      '};',
+      '',
+      '// CORRECT: keep the built-in dialog',
+      'form.successCallback = async data => {',
+      '  track(data);',
+      '  return true;',
+      '};',
+      '',
+      '// CORRECT: deliberately replace the built-in dialog with your own UI',
+      'form.successCallback = async data => {',
+      '  showMyOwnPanel(data);',
+      '  return false;',
+      '};',
+    ].join('\n'),
+  },
+  {
+    id: 'step-change-callback-is-dead',
+    title: 'stepChangeCallback is declared but never invoked.',
+    detail: [
+      'grep over src/ finds the identifier in exactly three kinds of place: the five @Prop',
+      'declarations (general-form, general-inquiry, service-booking, test-drive,',
+      'ssc-lookup), the optional field on FormHookInterface, and the generated entries in',
+      'components.d.ts. There is no call site anywhere. Assigning it is a no-op.',
+      '',
+      'vehicle-quotation-form does not even declare it.',
+      '',
+      'There is currently no push notification of a step change. Read the current step',
+      'from the hook, or wrap updateStep yourself if you need to be told.',
+    ].join('\n'),
+    example: [
+      '// does nothing at all',
+      'el.stepChangeCallback = (step, currentForm) => console.log(step);',
+      '',
+      '// read it instead',
+      'const hook = await el.getForm();',
+      'console.log(hook.formStructure?.currentStep); // 1-based',
+      '',
+      '// or intercept the mutator, if you must be notified',
+      'const originalUpdateStep = hook.updateStep;',
+      'hook.updateStep = (step, replace) => {',
+      '  onStepChange(step);',
+      '  return originalUpdateStep(step, replace);',
+      '};',
+    ].join('\n'),
+  },
+  {
+    id: 'language-is-guessed-from-the-url',
+    title: 'Leaving `language` off does not give you English — it gives you whatever the URL looks like.',
+    detail: [
+      'componentWillLoad runs `if (!this.language) this.language = getLanguageFromUrl()`,',
+      'and that function is a substring matcher:',
+      '',
+      '  1. ?lang= / ?lng= / ?language=, lower-cased, matched against the keys',
+      '     en, english, ar, arabic, ku, ckb, kurdish, sorani, ru, russian;',
+      '  2. otherwise, for each of those keys in that order,',
+      '       location.pathname.toLowerCase().includes("/" + key)',
+      '  3. otherwise "en".',
+      '',
+      'Step 2 is not segment-aware. Any path containing "/ar" resolves to Arabic and flips',
+      'the form to RTL; any path containing "/ru" resolves to Russian; "/ku", "/ckb" and',
+      '"/sorani" resolve to Kurdish. Real English paths that break: /parts/archive,',
+      '/support/articles, /news/around-the-world, /shop/rugs (matches "/ru").',
+      '',
+      'The prop is reflect: true, so after the guess you will see language="ar" sitting on',
+      'the element in DevTools, which makes it look intentional.',
+    ].join('\n'),
+    example: [
+      '<!-- page served at https://example.invalid/parts/archive -->',
+      '',
+      '<!-- WRONG: renders in Arabic, right-to-left -->',
+      '<general-form></general-form>',
+      '',
+      '<!-- RIGHT: always state it -->',
+      '<general-form language="en"></general-form>',
+      '',
+      '<script>',
+      '  // and when the host page switches language, assign it - this IS watched',
+      "  document.querySelector('general-form').language = 'ku';",
+      '</script>',
+    ].join('\n'),
+  },
+  {
+    id: 'extra-payload-header-precedence-asymmetry',
+    title: 'The prop wins for the payload; the structure wins for the headers.',
+    detail: [
+      'Both merges live a few lines apart in functions.ts, and they run in opposite orders.',
+      '',
+      '  // payload - structure first, prop second => PROP WINS',
+      '  if (structure?.data?.extraPayload) payload = { ...payload, ...structure.data.extraPayload };',
+      '  if (extraPayload)                  payload = { ...payload, ...extraPayload };',
+      '',
+      '  // headers - prop first, structure second => STRUCTURE WINS',
+      '  if (extraHeader)                  header = { ...header, ...extraHeader };',
+      '  if (structure?.data?.extraHeader) header = { ...header, ...structure.data.extraHeader };',
+      '',
+      'So the same override strategy gives opposite results depending on which one you use.',
+      'If a header you set from JavaScript is not arriving, look for the same key in',
+      'structure.data.extraHeader.',
+    ].join('\n'),
+    example: [
+      "form.structure = { data: { extraPayload: { source: 'structure' }, extraHeader: { 'X-Source': 'structure' } }, tag: 'div', children: [] };",
+      "form.extraPayload = { source: 'prop' };",
+      "form.extraHeader  = { 'X-Source': 'prop' };",
+      '',
+      "// body   -> { source: 'prop' }        (the prop won)",
+      "// header -> { 'X-Source': 'structure' } (the structure won)",
+    ].join('\n'),
+  },
+  {
+    id: 'is-dev-is-only-a-string-replace',
+    title: 'is-dev is a text substitution in the URL, not a mock switch.',
+    detail: [
+      'The entire implementation is one line, executed just before the fetch:',
+      '',
+      '  if (context.isDev) requestEndpoint = requestEndpoint.replaceAll("production=true", "production=false");',
+      '',
+      'It does not enable mocks, does not point at a different structure, does not relax',
+      'validation, and does not skip reCAPTCHA. If the endpoint has no literal, lower-case',
+      '"production=true" in it, is-dev changes nothing whatsoever - which is exactly what',
+      'makes it look broken. It runs after the mobile/browser endpoint choice, so it',
+      'rewrites requestAppUrl and requestAppCheckUrl too.',
+    ].join('\n'),
+    example: [
+      "// requestUrl 'https://api.example.invalid/tickets?production=true'",
+      "//   + is-dev  -> 'https://api.example.invalid/tickets?production=false'  (works)",
+      '',
+      "// requestUrl 'https://api.example.invalid/tickets'",
+      '//   + is-dev  -> unchanged                                              (no-op)',
+      '',
+      "// requestUrl 'https://api.example.invalid/tickets?Production=True'",
+      '//   + is-dev  -> unchanged - the match is case-sensitive                (no-op)',
+    ].join('\n'),
+  },
+  {
+    id: 'is-mobile-form-key-presence-wins',
+    title: 'structure.data.isMobileForm overrides the prop by KEY PRESENCE, including when it is false.',
+    detail: [
+      'resolveIsMobileForm in functions.ts:',
+      '',
+      '  Object.hasOwn(structure?.data ?? {}, "isMobileForm")',
+      '    ? !!structure.data.isMobileForm',
+      '    : fallback   // the prop',
+      '',
+      'The comment in the source says why: "A present-but-false isMobileForm still has to',
+      'beat the prop, so this is a key check rather than a truthiness check." The practical',
+      'effect is that deleting the key and setting it to false are different things.',
+      '',
+      'vehicle-quotation-form calls the same helper, so the rule is identical there',
+      '',
+    ].join('\n'),
+    example: [
+      '// structure says false, tag says true -> mobile mode is OFF',
+      "form.structure = { data: { isMobileForm: false }, tag: 'div', children: [] };",
+      'form.isMobileForm = true;',
+      '',
+      '// remove the key entirely and the prop is honoured -> mobile mode is ON',
+      'delete form.structure.data.isMobileForm;',
+    ].join('\n'),
+  },
+  {
+    id: 'no-custom-events',
+    title: 'These components emit no custom events. Everything comes back through callbacks.',
+    detail: [
+      'There is no @Event() on any of the six form shells, nor anywhere in',
+      'src/features/form-hook. addEventListener("success", ...) and friends will never',
+      'fire. The only @Event() declarations in the repo belong to two inner pickers',
+      '(branch-date-picker and branch-slot-picker, both emitting `slotChange`); those are',
+      'internal wiring, not part of the form API.',
+      '',
+      'Use successCallback, errorCallback, loadingChanges and formReadyCallback - all of',
+      'which are property-only, so a markup-only integration has no way to observe the form.',
+    ].join('\n'),
+    example: [
+      '// does nothing - no such event is ever dispatched',
+      "el.addEventListener('formSubmitted', handler);",
+      '',
+      '// the supported equivalents',
+      'el.successCallback = async data => { handler(data); return true; };',
+      'el.errorCallback = async (error, message) => { onFail(message); return true; };',
+      'el.loadingChanges = busy => setBusy(busy);',
+      'el.formReadyCallback = () => onReady();',
+    ].join('\n'),
+  },
+  {
+    id: 'submit-resolves-before-the-request',
+    title: 'await el.submit() does not wait for the network.',
+    detail: [
+      'The @Method resolves as soon as it has handed off. FormHook.submit() calls',
+      'submitForm() without awaiting it, so the promise you get back settles long before',
+      'the fetch does. There is also a guard at the top of submitForm - if the form is',
+      'already loading (a submit in flight, or a file field still uploading) the call',
+      'returns immediately and silently.',
+      '',
+      'To know when a submit actually finished, use the callbacks.',
+    ].join('\n'),
+    example: [
+      '// WRONG - runs immediately, before the request has even been sent',
+      'await el.submit();',
+      "console.log('submitted');",
+      '',
+      '// RIGHT',
+      'el.loadingChanges = busy => {',
+      "  if (!busy) console.log('settled - success or error has already fired');",
+      '};',
+      "el.successCallback = async () => { console.log('submitted'); return true; };",
+      'el.submit();',
+    ].join('\n'),
+  },
+  {
+    id: 'utm-values-move-to-headers-on-get',
+    title: 'UTM values are collected automatically, and go into the HEADERS when the method is GET or HEAD.',
+    detail: [
+      'On every submit, functions.ts reads utm_source, utm_medium, utm_campaign, utm_term,',
+      'utm_content, gclid and fbclid from the current page query string, and merges them',
+      '  * into the PAYLOAD for any method other than get/head,',
+      '  * into the HEADERS for get and head.',
+      '',
+      'Turn it off with structure.data.disableUTMLog: true, or per-visit with',
+      '?disable_utm_log=true on the page URL.',
+      '',
+      'Because the merge happens after extraPayload/extraHeader, a UTM key collides with',
+      'and overwrites anything you set under the same name.',
+    ].join('\n'),
+    example: [
+      '// page: https://example.invalid/contact?utm_source=news&utm_campaign=spring',
+      '',
+      "// requestMethod 'POST' -> body gains  { utm_source: 'news', utm_campaign: 'spring' }",
+      "// requestMethod 'GET'  -> headers gain { utm_source: 'news', utm_campaign: 'spring' }",
+      '',
+      '// opt out for this form',
+      "form.structure = { data: { disableUTMLog: true, requestUrl: 'https://api.example.invalid/tickets' }, tag: 'div', children: [] };",
+    ].join('\n'),
+  },
+  {
+    id: 'vehicle-quotation-ignores-extra-props',
+    title: 'vehicle-quotation-form declares extraHeader and extraPayload and reads neither.',
+    detail: [
+      'It does not go through functionHooks.onFormSubmit. Its formSubmit is written by hand:',
+      'it builds a mapped payload, builds headers inline as Brand / Accept-Language /',
+      'Content-Type, merges structure.data.extraPayload only, and always POSTs.',
+      '',
+      'So on this component:',
+      '  * the extraHeader prop is inert, with no structure-level substitute;',
+      '  * the extraPayload prop is inert - use structure.data.extraPayload;',
+      '  * structure.data.requestMethod is ignored (always POST);',
+      '  * structure.data.truncatedFields is ignored;',
+      '  * there is no `theme` prop - only structure.data.theme, which renders as',
+      '    part="vehicle-quotation-<theme>";',
+      '  * grecaptcha.execute is called unconditionally in browser mode, so a structure',
+      '    with no recaptchaKey fails at submit instead of posting;',
+      '  * Object.hasOwn(this.structure?.data, "isMobileForm") has no ?? {} guard, so a',
+      '    structure with no data object throws at submit.',
+      '',
+      'The generated types advertise the inert props, so TypeScript will not warn you.',
+    ].join('\n'),
+    example: [
+      "const form = document.querySelector('vehicle-quotation-form');",
+      '',
+      '// IGNORED on this component',
+      "form.extraPayload = { campaign: 'spring' };",
+      "form.extraHeader = { 'X-Source': 'docs' };",
+      '',
+      '// the working equivalent for the payload',
+      'form.structure = {',
+      '  data: {',
+      "    requestUrl: 'https://api.example.invalid/quotations',",
+      "    quotationType: 'NewVehicle',",
+      "    extraPayload: { campaign: 'spring' },   // this one IS merged",
+      '  },',
+      "  tag: 'div',",
+      "  children: [{ name: 'vehicle' }, { name: 'dealer' }, { name: 'name' }, { name: 'phone' }, { name: 'submit' }],",
+      '};',
+      '',
+      '// there is no equivalent for the header - the header set is closed',
+    ].join('\n'),
+  },
+  {
+    id: 'form-ready-fires-once-and-early',
+    title: 'formReadyCallback fires once, ~300 ms after the fields mount, and only if it was assigned in time.',
+    detail: [
+      'The inner form-structure sets context.structureRendered = true from a 300 ms',
+      'setTimeout in its componentDidLoad, and @Watch("structureRendered") calls',
+      'formReadyCallback on that false -> true transition. structureRendered never goes',
+      'back to false, so the callback never fires a second time - not on a language change,',
+      'not on a post-submit reset, not on a re-render.',
+      '',
+      'Assign it before the element is connected. Assigning it after the transition has',
+      'already happened means it is simply never called.',
+      '',
+      'It is also the only reliable signal that getForm() will resolve to something:',
+      'getForm() returns undefined until componentDidLoad has constructed the hook.',
+    ].join('\n'),
+    example: [
+      "const el = document.createElement('general-form');",
+      '',
+      "el.language = 'en';",
+      'el.structure = structure;',
+      'el.formReadyCallback = async () => {',
+      '  const hook = await el.getForm();',
+      "  hook.setCachedValues({ source: 'docs' });",
+      '};',
+      '',
+      "document.getElementById('form-slot').appendChild(el); // assign first, THEN connect",
+    ].join('\n'),
+  },
+  {
+    id: 'markup-only-integration-is-not-enough',
+    title: 'A form configured purely from HTML attributes cannot report anything back.',
+    detail: [
+      'Only eight props have attributes: language, gist-id, structure-url, theme, form-id,',
+      'is-dev, disable-scroll-to-top and is-mobile-form. Everything else - the structure,',
+      'the field overrides, every callback, the extra payload and headers, and the mobile',
+      'token supplier - is property-only.',
+      '',
+      'And since the components emit no custom events, a markup-only page has no way to',
+      'observe a submit at all. Any real integration needs a small script.',
+      '',
+      '(vehicle-quotation-form has seven attributes - the same list without `theme`.)',
+    ].join('\n'),
+    example: [
+      '<general-form',
+      '  id="contact"',
+      '  language="en"',
+      '  structure-url="https://cdn.example.invalid/forms/contact.json"',
+      '></general-form>',
+      '',
+      '<script>',
+      "  const el = document.getElementById('contact');",
+      "  el.formReadyCallback = () => console.log('ready');",
+      "  el.loadingChanges = busy => document.body.classList.toggle('is-submitting', busy);",
+      '  el.successCallback = async () => true;  // remember the return',
+      '  el.errorCallback = async () => true;    // remember the return',
+      '</script>',
+    ].join('\n'),
+  },
+];