@teleporthq/teleport-project-generator-html 0.43.70 → 0.43.72

package/__tests__/_helpers/state-site.ts

@@ -0,0 +1,210 @@
+import { GeneratedFolder, ProjectUIDL } from '@teleporthq/teleport-types'
+import uidlSample from '../../../../examples/uidl-samples/tests.json'
+import {
+  createHTMLProjectGenerator,
+  pluginHomeReplace,
+  pluginStateRuntime,
+  ProjectPluginCloneGlobals,
+} from '../../src'
+import HTMLTemplate from '../../src/project-template'
+
+/**
+ * A home page the way the editor exports its interactive library pieces: a
+ * Navigation component whose burger toggles its own menu, used twice (the
+ * first instance holds slot content that reads the PAGE's state), a tab set
+ * wired by the editor's click workflows with a state class on every trigger,
+ * and a monthly / yearly price switch.
+ */
+
+const s = (content: unknown) => ({ type: 'static', content })
+const state = (id: string) => ({ type: 'dynamic', content: { referenceType: 'state', id } })
+const el = (elementType: string, content: Record<string, unknown> = {}) => ({
+  type: 'element',
+  content: { elementType, ...content },
+})
+const text = (id: string, label: string) =>
+  el('text', { semanticType: 'span', attrs: { id: s(id) }, children: [s(label)] })
+const when = (id: string, operation: string, operand: unknown, node: unknown) => ({
+  type: 'conditional',
+  content: { reference: state(id), node, condition: { conditions: [{ operation, operand }] } },
+})
+const styles = (map: Record<string, string>) =>
+  Object.fromEntries(Object.entries(map).map(([key, value]) => [key, s(value)]))
+
+const NAVIGATION = {
+  name: 'Navigation',
+  stateDefinitions: { menuOpen: { type: 'boolean', defaultValue: false } },
+  node: el('container', {
+    name: 'bar',
+    style: styles({ display: 'flex', gap: '16px', padding: '16px', alignItems: 'center' }),
+    children: [
+      el('container', {
+        name: 'burger',
+        attrs: { id: s('burger'), 'aria-label': s('Menu') },
+        style: styles({ width: '48px', height: '48px', background: '#ddd' }),
+        events: { click: [{ type: 'stateChange', modifies: 'menuOpen', newState: '$toggle' }] },
+        children: [
+          when('menuOpen', '===', false, text('burger-open', 'Open')),
+          when('menuOpen', '===', true, text('burger-close', 'Close')),
+        ],
+      }),
+      when(
+        'menuOpen',
+        '===',
+        true,
+        el('container', {
+          name: 'menu',
+          attrs: { id: s('menu') },
+          style: styles({ display: 'flex', gap: '8px' }),
+          children: [text('menu-home', 'Home'), text('menu-about', 'About')],
+        })
+      ),
+      { type: 'slot', content: {} },
+    ],
+  }),
+}
+
+const TAB_ACTIVE = 'tab-active'
+
+const tabTrigger = (index: number) =>
+  el('container', {
+    name: `tab-trigger-${index}`,
+    attrs: { id: s(`tab-${index}`), 'data-tab-index': s(String(index)) },
+    style: styles({ padding: '12px 24px', cursor: 'pointer' }),
+    referencedStyles: {
+      [`active-${index}`]: {
+        type: 'style-map',
+        content: {
+          mapType: 'project-referenced',
+          referenceId: TAB_ACTIVE,
+          condition: {
+            reference: state('activeTabIndex'),
+            expression: { conditions: [{ operation: '=', operand: index }] },
+          },
+        },
+      },
+    },
+    children: [s(`Tab ${index + 1}`)],
+  })
+
+const tabPanel = (index: number) =>
+  when(
+    'activeTabIndex',
+    '=',
+    index,
+    el('container', {
+      name: `tab-panel-${index}`,
+      attrs: { id: s(`panel-${index}`) },
+      style: styles({ display: 'flex', padding: '24px', minHeight: '120px' }),
+      children: [s(`Panel ${index + 1}`)],
+    })
+  )
+
+const tabWorkflow = (index: number) => ({
+  id: `switch-tab-${index}`,
+  name: `Switch to Tabs Tab ${index + 1}`,
+  trigger: {
+    nodeId: `trigger-${index}`,
+    type: 'event-element-clicked',
+    scope: 'element',
+    config: { nodeId: `doc-${index}`, elementHtmlId: `tab-${index}`, preventDefault: false },
+  },
+  nodes: [
+    {
+      id: `set-${index}`,
+      type: 'state-update-local-state',
+      label: 'Set Local State',
+      config: { property: 'activeTabIndex', value: index },
+      executionEnv: 'client',
+      stepNumber: 1,
+    },
+  ],
+  edges: [{ id: `edge-${index}`, source: `trigger-${index}`, target: `set-${index}` }],
+  errorHandler: {
+    nodeId: `error-${index}`,
+    type: 'event-workflow-error',
+    config: { isErrorHandler: true },
+    executionEnv: 'client',
+  },
+  usedInNodes: { [`doc-${index}`]: true },
+})
+
+const HOME_CHILDREN = [
+  el('component', {
+    semanticType: 'Navigation',
+    dependency: { type: 'local' },
+    children: [when('yearly', '===', true, text('slot-badge', 'Yearly billing'))],
+  }),
+  el('component', { semanticType: 'Navigation', dependency: { type: 'local' } }),
+  el('container', {
+    name: 'tabs',
+    attrs: { id: s('tabs') },
+    style: styles({ display: 'flex' }),
+    children: [0, 1, 2].map(tabTrigger),
+  }),
+  ...[0, 1, 2].map(tabPanel),
+  el('button', {
+    name: 'billing-switch',
+    attrs: { id: s('billing-switch') },
+    events: { click: [{ type: 'stateChange', modifies: 'yearly', newState: '$toggle' }] },
+    children: [s('Bill yearly')],
+  }),
+  when('yearly', '===', false, text('price-monthly', '$19 / month')),
+  when('yearly', '===', true, text('price-yearly', '$190 / year')),
+]
+
+const sample = () => JSON.parse(JSON.stringify(uidlSample))
+
+export const plainSite = (): ProjectUIDL => sample()
+
+export const stateSite = (): ProjectUIDL => {
+  const uidl = sample()
+  uidl.root.styleSetDefinitions = {
+    ...(uidl.root.styleSetDefinitions || {}),
+    [TAB_ACTIVE]: {
+      type: 'reusable-project-style-map',
+      content: styles({ color: '#c00', borderBottom: '2px solid #c00' }),
+    },
+  }
+  uidl.components.Navigation = NAVIGATION
+  uidl.workflows = {
+    workflows: Object.fromEntries(
+      [0, 1, 2].map((index) => [`switch-tab-${index}`, tabWorkflow(index)])
+    ),
+  }
+  const homeRoute = uidl.root.stateDefinitions.route.values.find(
+    (route: { value: string }) => route.value === uidl.root.stateDefinitions.route.defaultValue
+  )
+  homeRoute.pageOptions = {
+    ...(homeRoute.pageOptions || {}),
+    stateDefinitions: {
+      activeTabIndex: { type: 'number', defaultValue: 0 },
+      yearly: { type: 'boolean', defaultValue: false },
+    },
+  }
+  uidl.root.node.content.children[0].content.node.content.children = HOME_CHILDREN
+  return uidl
+}
+
+export const generateSite = async (
+  uidl: ProjectUIDL,
+  { strictHtmlWhitespaceSensitivity = false } = {}
+): Promise<GeneratedFolder> => {
+  if (strictHtmlWhitespaceSensitivity) {
+    // custom head code that ends in a script makes Prettier close the head as `</head\n  >`
+    uidl.globals.customCode = { head: '<script>\n  window.tqHeadReady = true\n</script>' }
+  }
+  const generator = createHTMLProjectGenerator()
+  generator.addPlugin(pluginHomeReplace)
+  generator.addPlugin(new ProjectPluginCloneGlobals({ strictHtmlWhitespaceSensitivity }))
+  generator.addPlugin(pluginStateRuntime)
+  return generator.generateProject(
+    uidl as unknown as Record<string, unknown>,
+    HTMLTemplate,
+    {},
+    strictHtmlWhitespaceSensitivity
+  )
+}
+
+export const fileOf = (folder: GeneratedFolder, name: string, fileType: string) =>
+  folder.files.find((file) => file.name === name && file.fileType === fileType)?.content ?? ''

package/__tests__/conditionals/index.ts

@@ -0,0 +1,208 @@
+import { FileType, ProjectUIDL } from '@teleporthq/teleport-types'
+import uidlSample from '../../../../examples/uidl-samples/tests.json'
+import { createHTMLProjectGenerator, pluginCloneGlobals, pluginHomeReplace } from '../../src'
+import HTMLTemplate from '../../src/project-template'
+
+/**
+ * An element shown on a condition appears as the page first loads in the
+ * Next.js export: the condition is resolved against the value its reference
+ * starts with. Until 2026-09-18 every STATE condition rendered nothing, true
+ * or not, so a download lost the burger of a closed menu and the first tab of
+ * every tab set. Since 2026-10-04 a condition on the page's own state keeps
+ * every branch in the page for the state runtime to switch, and the ones the
+ * page does not start on are `hidden` (state-runtime/ covers the runtime); a
+ * condition on anything else is still resolved once.
+ */
+const s = (content: unknown) => ({ type: 'static', content })
+const span = (id: string) => ({
+  type: 'element',
+  content: { elementType: 'text', semanticType: 'span', attrs: { id: s(id) }, children: [s(id)] },
+})
+const when = (
+  reference: Record<string, unknown>,
+  conditions: Array<Record<string, unknown>>,
+  id: string
+) => ({
+  type: 'conditional',
+  content: { reference, node: span(id), condition: { conditions, matchingCriteria: 'all' } },
+})
+const state = (id: string, refPath?: string[]) => ({
+  type: 'dynamic',
+  content: { referenceType: 'state', id, ...(refPath ? { refPath } : {}) },
+})
+const prop = (id: string) => ({ type: 'dynamic', content: { referenceType: 'prop', id } })
+
+const homePage = async (
+  children: unknown[],
+  stateDefinitions: Record<string, unknown>,
+  propDefinitions: Record<string, unknown> = {}
+): Promise<string> => {
+  const uidl = JSON.parse(JSON.stringify(uidlSample))
+  const home = uidl.root.node.content.children[0].content.node.content
+  home.children = children
+  // A page's own state and props travel with its route, as the editor exports them.
+  const homeRoute = uidl.root.stateDefinitions.route.values.find(
+    (route: { value: string }) => route.value === uidl.root.stateDefinitions.route.defaultValue
+  )
+  homeRoute.pageOptions = { ...(homeRoute.pageOptions || {}), stateDefinitions, propDefinitions }
+  const generator = createHTMLProjectGenerator()
+  generator.addPlugin(pluginHomeReplace)
+  generator.addPlugin(pluginCloneGlobals)
+  const { files } = await generator.generateProject(uidl as ProjectUIDL, HTMLTemplate)
+  return (
+    files.find((file) => file.name === 'index' && file.fileType === FileType.HTML)?.content ?? ''
+  )
+}
+
+const openingTag = (page: string, id: string) =>
+  new RegExp(`<[a-z][^>]*\\bid="${id}"[^>]*>`).exec(page)?.[0]
+const inPage = (page: string, id: string) => openingTag(page, id) !== undefined
+/** In the markup and not `hidden`: what a visitor sees before any script runs. */
+const shows = (page: string, id: string) =>
+  inPage(page, id) && !/\shidden(=""|\s|>)/.test(openingTag(page, id) ?? '')
+
+describe('Conditions in a static HTML page', () => {
+  it('a state condition shows what the page starts with, and keeps the rest hidden for the runtime', async () => {
+    const page = await homePage(
+      [
+        when(state('menuOpen'), [{ operation: '===', operand: true }], 'menu-panel'),
+        when(state('menuOpen'), [{ operation: '===', operand: false }], 'burger'),
+        when(state('tab'), [{ operation: '===', operand: 'a' }], 'tab-a'),
+        when(state('tab'), [{ operation: '===', operand: 'b' }], 'tab-b'),
+      ],
+      {
+        menuOpen: { type: 'boolean', defaultValue: false },
+        tab: { type: 'string', defaultValue: 'a' },
+      }
+    )
+
+    expect(shows(page, 'burger')).toBe(true)
+    expect(shows(page, 'tab-a')).toBe(true)
+    expect(shows(page, 'menu-panel')).toBe(false)
+    expect(shows(page, 'tab-b')).toBe(false)
+    expect(inPage(page, 'menu-panel')).toBe(true)
+    expect(inPage(page, 'tab-b')).toBe(true)
+    expect(openingTag(page, 'menu-panel')).toContain('data-tq-if="menuOpen"')
+    expect(openingTag(page, 'burger')).toContain('data-tq-if="!menuOpen"')
+    expect(openingTag(page, 'tab-b')).toContain(`data-tq-if="tab === 'b'"`)
+    expect(page).toContain(`data-tq-state="menuOpen = false; tab = 'a'"`)
+  })
+
+  it('reads into an object state and compares numbers, once: the runtime keeps no objects', async () => {
+    const page = await homePage(
+      [
+        when(state('cart', ['count']), [{ operation: '>', operand: 0 }], 'cart-badge'),
+        when(state('cart', ['count']), [{ operation: '===', operand: 0 }], 'cart-empty'),
+      ],
+      { cart: { type: 'object', defaultValue: { count: 0 } } }
+    )
+
+    expect(shows(page, 'cart-empty')).toBe(true)
+    expect(inPage(page, 'cart-badge')).toBe(false)
+    expect(page).not.toContain('data-tq-')
+  })
+
+  it('a condition with no operand tests the value itself, as the JSX generators do', async () => {
+    const page = await homePage(
+      [
+        when(state('loading'), [{ operation: '!' }], 'content'),
+        when(prop('isPromo'), [{ operation: '!' }], 'regular-price'),
+      ],
+      { loading: { type: 'boolean', defaultValue: true } },
+      { isPromo: { type: 'boolean', defaultValue: false } }
+    )
+
+    // loading starts true: "not loading" is false, and the runtime can turn it on
+    expect(shows(page, 'content')).toBe(false)
+    expect(openingTag(page, 'content')).toContain('data-tq-if="!loading"')
+    // isPromo starts false: "not promo" is true; a prop never changes in a static page
+    expect(shows(page, 'regular-price')).toBe(true)
+    expect(openingTag(page, 'regular-price')).not.toContain('data-tq-if')
+  })
+
+  it('a condition on a list or an object is answered on what it starts with', async () => {
+    const page = await homePage(
+      [
+        when(state('lines'), [{ operation: 'isEmpty' }], 'cart-empty'),
+        when(state('lines'), [{ operation: 'isNotEmpty' }], 'cart-lines'),
+        when(state('picked'), [{ operation: 'isNotEmpty' }], 'some-picked'),
+        when(state('picked'), [{ operation: 'contains', operand: 'b' }], 'picked-b'),
+        when(state('picked'), [{ operation: 'notContains', operand: 'z' }], 'not-picked-z'),
+        when(state('picked'), [{ operation: 'contains', operand: 'z' }], 'picked-z'),
+        when(state('picked'), [{ operation: 'lengthGreaterThan', operand: 1 }], 'several'),
+        when(state('picked'), [{ operation: 'lengthEquals', operand: 3 }], 'three'),
+        when(
+          state('rows'),
+          [{ operation: 'contains', operand: 7, containsField: 'id' }],
+          'row-seven'
+        ),
+        when(state('filters'), [{ operation: 'hasKey', operand: 'size' }], 'by-size'),
+        when(state('filters'), [{ operation: 'notHasKey', operand: 'size' }], 'any-size'),
+        when(state('heading'), [{ operation: 'isNotEmpty' }], 'with-heading'),
+      ],
+      {
+        lines: { type: 'array', defaultValue: [] },
+        picked: { type: 'array', defaultValue: ['a', 'b'] },
+        rows: { type: 'array', defaultValue: [{ id: 7 }, { id: 9 }] },
+        filters: { type: 'object', defaultValue: { size: 'm' } },
+        heading: { type: 'string', defaultValue: 'Hello' },
+      }
+    )
+
+    const shown = [
+      'cart-empty',
+      'some-picked',
+      'picked-b',
+      'not-picked-z',
+      'several',
+      'row-seven',
+      'by-size',
+      'with-heading',
+    ]
+    const absent = ['cart-lines', 'picked-z', 'three', 'any-size']
+    expect(shown.filter((id) => !shows(page, id))).toEqual([])
+    expect(absent.filter((id) => inPage(page, id))).toEqual([])
+  })
+
+  it('a condition it cannot answer renders nothing, and the page is still exported', async () => {
+    const page = await homePage(
+      [
+        // a list is not a value `===` can be written against
+        when(state('lines'), [{ operation: '===', operand: 'x' }], 'list-equals'),
+        // the other side is read while the page runs
+        when(state('picked'), [{ operation: 'contains', operand: state('choice') }], 'by-choice'),
+        when(state('filters'), [{ operation: '!' }], 'no-filters'),
+        when(state('open'), [{ operation: '===', operand: true }], 'panel'),
+      ],
+      {
+        lines: { type: 'array', defaultValue: [] },
+        picked: { type: 'array', defaultValue: ['a'] },
+        filters: { type: 'object', defaultValue: {} },
+        choice: { type: 'string', defaultValue: 'a' },
+        open: { type: 'boolean', defaultValue: true },
+      }
+    )
+
+    expect(['list-equals', 'by-choice', 'no-filters'].filter((id) => inPage(page, id))).toEqual([])
+    expect(shows(page, 'panel')).toBe(true)
+  })
+
+  it('a value holding a quote still compares', async () => {
+    const quote = 'She said "yes"'
+    const page = await homePage(
+      [when(state('answer'), [{ operation: '===', operand: quote }], 'quoted')],
+      { answer: { type: 'string', defaultValue: quote } }
+    )
+
+    expect(shows(page, 'quoted')).toBe(true)
+  })
+
+  it('a state with no starting value shows nothing that depends on it', async () => {
+    const page = await homePage(
+      [when(state('unknown'), [{ operation: '===', operand: true }], 'depends')],
+      {}
+    )
+
+    expect(inPage(page, 'depends')).toBe(false)
+  })
+})

package/__tests__/end2end/index.ts

@@ -1,7 +1,13 @@
 import uidlSample from '../../../../examples/uidl-samples/tests.json'
 import invalidUidlSample from '../../../../examples/test-samples/project-invalid-sample.json'
 import projectWithSlot from '../../../../examples/test-samples/project-with-slot.json'
-import { createHTMLProjectGenerator, pluginCloneGlobals, pluginHomeReplace } from '../../src'
+import {
+  createHTMLProjectGenerator,
+  pluginCloneGlobals,
+  pluginHomeReplace,
+  pluginSnapIntoView,
+  pluginScrollRail,
+} from '../../src'
 import HTMLTemplate from '../../src/project-template'
 import { FileType } from '@teleporthq/teleport-types'
 
@@ -72,6 +78,73 @@ describe('Html Project Generator', () => {
     expect(indexFile?.content).toContain(`This is amazing, because this is a named-slot`)
   })
 
+  it('Snap into view: the native snap rule ships only when an element opts in', async () => {
+    const plain = createHTMLProjectGenerator()
+    plain.addPlugin(pluginSnapIntoView)
+    const untouched = await plain.generateProject(uidlSample, HTMLTemplate)
+    untouched.files.forEach((file) => expect(file.content).not.toContain('scroll-snap-type'))
+
+    const uidl = JSON.parse(JSON.stringify(uidlSample))
+    const about = uidl.root.node.content.children.find(
+      (child: { content: { value?: string } }) => child.content.value === 'About'
+    )
+    about.content.node.content.attrs = {
+      ...(about.content.node.content.attrs || {}),
+      'data-snap-into-view': { type: 'static', content: 'firm' },
+    }
+    const generator = createHTMLProjectGenerator()
+    generator.addPlugin(pluginSnapIntoView)
+    const snapped = await generator.generateProject(uidl, HTMLTemplate)
+
+    const globalCss = snapped.files.find(
+      (file) => file.name === 'style' && file.fileType === FileType.CSS
+    )
+    const aboutPage = snapped.files.find(
+      (file) => file.name === 'about' && file.fileType === FileType.HTML
+    )
+    const rulesCarrier = globalCss ? globalCss.content : aboutPage?.content || ''
+    expect(rulesCarrier).toContain('scroll-snap-type: y proximity')
+    expect(rulesCarrier).toContain('[data-snap-into-view="firm"]')
+    expect(rulesCarrier).toContain('[data-snap-into-view="gentle"]')
+    expect(rulesCarrier).not.toContain('mandatory')
+    expect(aboutPage?.content).toContain('data-snap-into-view="firm"')
+  })
+
+  it('Scroll rail: CSS in the global stylesheet, the wheel script per page, only when used', async () => {
+    const plain = createHTMLProjectGenerator()
+    plain.addPlugin(pluginScrollRail)
+    const untouched = await plain.generateProject(uidlSample, HTMLTemplate)
+    untouched.files.forEach((file) => {
+      expect(file.content).not.toContain('scroll-snap-type: x')
+      expect(file.content).not.toContain('data-scroll-rail-wheel')
+    })
+
+    const uidl = JSON.parse(JSON.stringify(uidlSample))
+    const about = uidl.root.node.content.children.find(
+      (child: { content: { value?: string } }) => child.content.value === 'About'
+    )
+    about.content.node.content.attrs = {
+      ...(about.content.node.content.attrs || {}),
+      'data-scroll-rail-snap': { type: 'static', content: 'gentle' },
+      'data-scroll-rail-wheel': { type: 'static', content: 'true' },
+    }
+    const generator = createHTMLProjectGenerator()
+    generator.addPlugin(pluginScrollRail)
+    const railed = await generator.generateProject(uidl, HTMLTemplate)
+
+    const globalCss = railed.files.find(
+      (file) => file.name === 'style' && file.fileType === FileType.CSS
+    )
+    const aboutPage = railed.files.find(
+      (file) => file.name === 'about' && file.fileType === FileType.HTML
+    )
+    const rulesCarrier = globalCss ? globalCss.content : aboutPage?.content || ''
+    expect(rulesCarrier).toContain('scroll-snap-type: x proximity')
+    expect(rulesCarrier).toContain('scroll-snap-align: start')
+    expect(aboutPage?.content).toContain('data-scroll-rail-snap="gentle"')
+    expect(aboutPage?.content).toContain("addEventListener('wheel'")
+  })
+
   it('throws error when invalid UIDL sample is used', async () => {
     const generator = createHTMLProjectGenerator()
     const result = generator.generateProject(invalidUidlSample, HTMLTemplate)

package/__tests__/global-css/index.ts

@@ -0,0 +1,47 @@
+import { FileType, GeneratedFile, ProjectPluginStructure } from '@teleporthq/teleport-types'
+import { appendGlobalCss, appendPageScript } from '../../src/global-css'
+
+// A page as Prettier writes it with strict whitespace (the editor's "strict
+// white spacing for HTML" setting): no closing tag stands on its own.
+const STRICT_PAGE = [
+  '<!DOCTYPE html>',
+  '<html lang="en"',
+  '  ><head',
+  '    ><title>Home</title',
+  '  ></head',
+  '  ><body',
+  '    ><div>Content</div',
+  '  ></body',
+  '></html>',
+].join('\n')
+
+const structureWith = (page: string): ProjectPluginStructure =>
+  ({
+    files: new Map([
+      ['index', { path: [''], files: [{ name: 'index', fileType: FileType.HTML, content: page }] }],
+    ]),
+  } as unknown as ProjectPluginStructure)
+
+const pageOf = (structure: ProjectPluginStructure): string =>
+  (structure.files.get('index').files as GeneratedFile[])[0].content
+
+describe('Global CSS and page scripts in a page whose tags close the strict way', () => {
+  it('a project without a stylesheet carries the CSS inside the head, after the doctype', () => {
+    const structure = structureWith(STRICT_PAGE)
+    appendGlobalCss(structure, '.rail { overflow: hidden; }\n')
+    const page = pageOf(structure)
+
+    expect(page.startsWith('<!DOCTYPE html>')).toBe(true)
+    expect(page.indexOf('<style>')).toBeGreaterThan(page.indexOf('<head'))
+    expect(page.indexOf('.rail { overflow: hidden; }')).toBeLessThan(page.search(/<\/head\s*>/))
+  })
+
+  it('a page script runs at the end of the body', () => {
+    const structure = structureWith(STRICT_PAGE)
+    appendPageScript(structure, 'window.ready = true')
+    const page = pageOf(structure)
+
+    expect(page.indexOf('window.ready = true')).toBeGreaterThan(page.indexOf('<div>Content</div'))
+    expect(page.indexOf('window.ready = true')).toBeLessThan(page.search(/<\/body\s*>/))
+  })
+})