@pilotiq/pilotiq 0.1.0

package/src/schema/primes.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveSchema, _resetResolverRegistry } from './resolveSchema.js'
+import { Image } from './Image.js'
+import { Icon } from './Icon.js'
+import { Text } from './Text.js'
+import { Markdown } from './Markdown.js'
+import { Html } from './Html.js'
+import { UnorderedList } from './UnorderedList.js'
+
+beforeEach(() => _resetResolverRegistry())
+
+describe('Image prime', () => {
+  it('serializes url + defaults', async () => {
+    const tree = [Image.make('https://cdn.example.com/avatar.png')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!.type,  'image')
+    assert.equal(out[0]!['url'],   'https://cdn.example.com/avatar.png')
+    assert.equal(out[0]!['alt'],   '')
+    assert.equal(out[0]!['shape'], 'square')
+    assert.equal(out[0]!['width'],  undefined)
+    assert.equal(out[0]!['height'], undefined)
+  })
+
+  it('honors alt / width / height / circle', async () => {
+    const tree = [Image.make('a.png').alt('avatar').width(64).height(48).circle()]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['alt'],    'avatar')
+    assert.equal(out[0]!['width'],  64)
+    assert.equal(out[0]!['height'], 48)
+    assert.equal(out[0]!['shape'],  'circle')
+  })
+
+  it('size() sugar fills both dimensions', async () => {
+    const tree = [Image.make('a.png').size(40)]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['width'],  40)
+    assert.equal(out[0]!['height'], 40)
+  })
+
+  it('rounded() sets shape', async () => {
+    const tree = [Image.make('a.png').rounded()]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['shape'], 'rounded')
+  })
+})
+
+describe('Icon prime', () => {
+  it('serializes name + defaults', async () => {
+    const tree = [Icon.make('check')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!.type,  'icon')
+    assert.equal(out[0]!['name'],  'check')
+    assert.equal(out[0]!['size'],  16)
+    assert.equal(out[0]!['color'], 'default')
+    assert.equal(out[0]!['label'], undefined)
+  })
+
+  it('honors size / color / label', async () => {
+    const tree = [Icon.make('check').size(24).color('success').label('Done')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['size'],  24)
+    assert.equal(out[0]!['color'], 'success')
+    assert.equal(out[0]!['label'], 'Done')
+  })
+})
+
+describe('Text formatting setters', () => {
+  it('plain Text emits no formatting keys', async () => {
+    const tree = [Text.make('hello')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!.type,    'text')
+    assert.equal(out[0]!['content'], 'hello')
+    assert.equal(out[0]!['color'],   undefined)
+    assert.equal(out[0]!['size'],    undefined)
+    assert.equal(out[0]!['weight'],  undefined)
+    assert.equal(out[0]!['badge'],   undefined)
+  })
+
+  it('color / size / weight ride through', async () => {
+    const tree = [Text.make('hi').color('success').size('lg').weight('semibold')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['color'],  'success')
+    assert.equal(out[0]!['size'],   'lg')
+    assert.equal(out[0]!['weight'], 'semibold')
+  })
+
+  it('badge() flips on the pill rendering flag', async () => {
+    const tree = [Text.make('Active').badge()]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['badge'], true)
+    assert.equal(out[0]!['badgeColor'], undefined)
+  })
+
+  it('badgeColor() implies badge=true', async () => {
+    const tree = [Text.make('Pending').badgeColor('warning')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['badge'],      true)
+    assert.equal(out[0]!['badgeColor'], 'warning')
+  })
+
+  it('badge(false) disables the flag', async () => {
+    const tree = [Text.make('hi').badge(false)]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['badge'], undefined)
+  })
+})
+
+describe('Markdown prime', () => {
+  it('serializes converted html + defaults', async () => {
+    const tree = [Markdown.make('# hi\n\n**bold**')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!.type, 'markdown')
+    const html = String(out[0]!['html'])
+    assert.match(html, /<h1[^>]*>hi<\/h1>/)
+    assert.match(html, /<strong>bold<\/strong>/)
+    assert.equal(out[0]!['prose'], true)
+    assert.equal(out[0]!['size'],  undefined)
+  })
+
+  it('prose(false) disables the typographic wrapper flag', async () => {
+    const tree = [Markdown.make('hi').prose(false)]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['prose'], false)
+  })
+
+  it('size() flows through', async () => {
+    const tree = [Markdown.make('hi').size('lg')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['size'], 'lg')
+  })
+
+  it('breaks() converts single line breaks to <br>', async () => {
+    const tree = [Markdown.make('one\ntwo').breaks()]
+    const out = await resolveSchema(tree)
+    assert.match(String(out[0]!['html']), /<br/)
+  })
+
+  it('default (breaks=false) joins single line breaks', async () => {
+    const tree = [Markdown.make('one\ntwo')]
+    const out = await resolveSchema(tree)
+    assert.doesNotMatch(String(out[0]!['html']), /<br/)
+  })
+
+  it('sanitizes <script> tags by default', async () => {
+    const tree = [Markdown.make('hi\n\n<script>alert(1)</script>')]
+    const out  = await resolveSchema(tree)
+    const html = String(out[0]!['html'])
+    assert.doesNotMatch(html, /<script/i)
+    assert.doesNotMatch(html, /alert\(1\)/)
+  })
+
+  it('strips javascript: hrefs by default', async () => {
+    const tree = [Markdown.make('[evil](javascript:alert(1))')]
+    const out  = await resolveSchema(tree)
+    const html = String(out[0]!['html'])
+    assert.doesNotMatch(html, /javascript:/i)
+  })
+
+  it('allowRaw() preserves <script> for trusted sources', async () => {
+    const tree = [Markdown.make('hi\n\n<script>alert(1)</script>').allowRaw()]
+    const out  = await resolveSchema(tree)
+    const html = String(out[0]!['html'])
+    assert.match(html, /<script>alert\(1\)<\/script>/)
+  })
+
+  it('sanitize(false) is the explicit opt-out form', async () => {
+    const tree = [Markdown.make('<script>x</script>').sanitize(false)]
+    const out  = await resolveSchema(tree)
+    assert.match(String(out[0]!['html']), /<script>x<\/script>/)
+  })
+
+  it('sanitize({ config }) widens the allowlist for trusted CMS HTML', async () => {
+    const tree = [
+      Markdown.make('<iframe src="https://x.test/embed"></iframe>')
+        .sanitize({ allowedTags: ['iframe'], allowedAttributes: { iframe: ['src'] } }),
+    ]
+    const out  = await resolveSchema(tree)
+    const html = String(out[0]!['html'])
+    assert.match(html, /<iframe src="https:\/\/x\.test\/embed"><\/iframe>/)
+  })
+})
+
+describe('Html prime', () => {
+  it('passes safe html through after default sanitization', async () => {
+    const tree = [Html.make('<p>hi <em>there</em></p>')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!.type, 'html')
+    assert.equal(out[0]!['html'], '<p>hi <em>there</em></p>')
+    assert.equal(out[0]!['prose'], true)
+  })
+
+  it('prose(false) flips the wrapper flag off', async () => {
+    const tree = [Html.make('<p>hi</p>').prose(false)]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['prose'], false)
+  })
+
+  it('size() flows through', async () => {
+    const tree = [Html.make('<p>hi</p>').size('sm')]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['size'], 'sm')
+  })
+
+  it('strips <script> by default', async () => {
+    const tree = [Html.make('<p>ok</p><script>steal()</script>')]
+    const out  = await resolveSchema(tree)
+    const html = String(out[0]!['html'])
+    assert.doesNotMatch(html, /<script/i)
+    assert.doesNotMatch(html, /steal\(\)/)
+    assert.match(html, /<p>ok<\/p>/)
+  })
+
+  it('strips inline event handlers by default', async () => {
+    const tree = [Html.make('<a href="https://ok" onclick="x()">link</a>')]
+    const out  = await resolveSchema(tree)
+    const html = String(out[0]!['html'])
+    assert.doesNotMatch(html, /onclick/i)
+    assert.match(html, /href="https:\/\/ok"/)
+  })
+
+  it('allowRaw() preserves <script>', async () => {
+    const tree = [Html.make('<script>raw</script>').allowRaw()]
+    const out  = await resolveSchema(tree)
+    assert.equal(out[0]!['html'], '<script>raw</script>')
+  })
+
+  it('custom config widens the allowlist', async () => {
+    const tree = [
+      Html.make('<iframe src="https://x.test"></iframe>')
+        .sanitize({ allowedTags: ['iframe'], allowedAttributes: { iframe: ['src'] } }),
+    ]
+    const out = await resolveSchema(tree)
+    assert.equal(out[0]!['html'], '<iframe src="https://x.test"></iframe>')
+  })
+})
+
+describe('UnorderedList prime', () => {
+  it('serializes items array + defaults', async () => {
+    const tree = [UnorderedList.make(['one', 'two', 'three'])]
+    const out  = await resolveSchema(tree)
+    assert.equal(out[0]!.type, 'unorderedList')
+    assert.deepEqual(out[0]!['items'], ['one', 'two', 'three'])
+    assert.equal(out[0]!['color'],  undefined)
+    assert.equal(out[0]!['size'],   undefined)
+    assert.equal(out[0]!['weight'], undefined)
+  })
+
+  it('items() replaces the list', async () => {
+    const tree = [UnorderedList.make(['old']).items(['a', 'b'])]
+    const out  = await resolveSchema(tree)
+    assert.deepEqual(out[0]!['items'], ['a', 'b'])
+  })
+
+  it('make() with no args yields an empty list', async () => {
+    const tree = [UnorderedList.make()]
+    const out  = await resolveSchema(tree)
+    assert.deepEqual(out[0]!['items'], [])
+  })
+
+  it('color / size / weight flow through', async () => {
+    const tree = [UnorderedList.make(['x']).color('muted').size('lg').weight('semibold')]
+    const out  = await resolveSchema(tree)
+    assert.equal(out[0]!['color'],  'muted')
+    assert.equal(out[0]!['size'],   'lg')
+    assert.equal(out[0]!['weight'], 'semibold')
+  })
+})

package/src/schema/resolveSchema.test.ts

@@ -0,0 +1,329 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Element, type ElementMeta } from './Element.js'
+import {
+  resolveSchema,
+  registerResolver,
+  _resetResolverRegistry,
+} from './resolveSchema.js'
+import { Text } from './Text.js'
+import { Heading } from './Heading.js'
+import { Card } from './Card.js'
+
+beforeEach(() => _resetResolverRegistry())
+
+// ─── Test fixtures ──────────────────────────────────────────
+
+class TestLeaf extends Element {
+  constructor(private label: string) { super() }
+  getType() { return 'test-leaf' }
+  toMeta() { return { type: 'test-leaf' as const, label: this.label } }
+}
+
+class TestContainer extends Element {
+  constructor(children: Element[] = []) {
+    super()
+    this._children = children
+  }
+  getType() { return 'test-container' }
+  toMeta() { return { type: 'test-container' as const } }
+}
+
+// ─── Tests ──────────────────────────────────────────────────
+
+describe('resolveSchema', () => {
+  describe('input shapes', () => {
+    it('returns [] for undefined definition', async () => {
+      assert.deepEqual(await resolveSchema(undefined), [])
+    })
+
+    it('returns [] for empty array', async () => {
+      assert.deepEqual(await resolveSchema([]), [])
+    })
+
+    it('resolves a static array', async () => {
+      const result = await resolveSchema([new TestLeaf('one')])
+      assert.deepEqual(result, [{ type: 'test-leaf', label: 'one' }])
+    })
+
+    it('resolves an async factory function', async () => {
+      const factory = async () => [new TestLeaf('async')]
+      const result = await resolveSchema(factory)
+      assert.deepEqual(result, [{ type: 'test-leaf', label: 'async' }])
+    })
+
+    it('passes context to the factory function', async () => {
+      let received: unknown = null
+      const factory = async (ctx: unknown) => { received = ctx; return [] }
+      await resolveSchema(factory, { user: { name: 'test' } })
+      assert.deepEqual(received, { user: { name: 'test' } })
+    })
+  })
+
+  // ─── Container recursion ─────────────────────────────────
+
+  describe('container recursion', () => {
+    it('attaches resolved children to container meta as `children`', async () => {
+      const tree = [new TestContainer([new TestLeaf('a'), new TestLeaf('b')])]
+      const result = await resolveSchema(tree)
+      assert.equal(result.length, 1)
+      assert.equal(result[0]!.type, 'test-container')
+      assert.equal(result[0]!.children?.length, 2)
+      assert.equal(result[0]!.children![0]!.label, 'a')
+      assert.equal(result[0]!.children![1]!.label, 'b')
+    })
+
+    it('recurses through multiple levels', async () => {
+      const tree = [
+        new TestContainer([
+          new TestContainer([new TestLeaf('deep')]),
+        ]),
+      ]
+      const result = await resolveSchema(tree)
+      const depth1 = result[0]!.children![0] as ElementMeta
+      assert.equal(depth1.type, 'test-container')
+      assert.equal(depth1.children?.[0]?.label, 'deep')
+    })
+
+    it('omits `children` field when container has no children', async () => {
+      const tree = [new TestContainer([])]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!.children, undefined)
+    })
+
+    it('omits `children` field for leaves (getChildren returns undefined)', async () => {
+      const result = await resolveSchema([new TestLeaf('leaf')])
+      assert.equal(result[0]!.children, undefined)
+    })
+  })
+
+  // ─── Plugin registry ────────────────────────────────────
+
+  describe('plugin resolver registry', () => {
+    it('registered resolver replaces default toMeta+recurse behavior', async () => {
+      registerResolver('test-leaf', () => ({ type: 'test-leaf', custom: 'override' }))
+      const result = await resolveSchema([new TestLeaf('original')])
+      assert.deepEqual(result[0], { type: 'test-leaf', custom: 'override' })
+    })
+
+    it('registered resolver receives the original element', async () => {
+      let captured: Element | null = null
+      registerResolver('test-leaf', el => { captured = el; return el.toMeta() as ElementMeta })
+      await resolveSchema([new TestLeaf('hello')])
+      assert.ok(captured)
+      assert.equal((captured as Element).getType(), 'test-leaf')
+    })
+
+    it('registered resolver receives the recurse helper for custom child resolution', async () => {
+      registerResolver('test-container', async (el, _ctx, recurse) => {
+        const meta = el.toMeta() as ElementMeta
+        const children = el.getChildren()
+        if (children) {
+          // Custom: prepend a synthetic injected child to the resolved tree.
+          const resolved = await recurse(children)
+          meta.children = [{ type: 'injected' }, ...resolved]
+        }
+        return meta
+      })
+      const tree = [new TestContainer([new TestLeaf('a')])]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!.children?.length, 2)
+      assert.equal(result[0]!.children![0]!.type, 'injected')
+      assert.equal(result[0]!.children![1]!.type, 'test-leaf')
+    })
+
+    it('async resolvers are awaited', async () => {
+      registerResolver('test-leaf', async () => {
+        await new Promise(r => setTimeout(r, 5))
+        return { type: 'test-leaf', async: true }
+      })
+      const result = await resolveSchema([new TestLeaf('x')])
+      assert.deepEqual(result[0], { type: 'test-leaf', async: true })
+    })
+
+    it('non-registered types fall through to default behavior', async () => {
+      registerResolver('test-leaf', () => ({ type: 'test-leaf', overridden: true }))
+      const result = await resolveSchema([new TestContainer([new TestLeaf('x')])])
+      // Container falls through to default; leaf inside uses the registered resolver.
+      assert.equal(result[0]!.type, 'test-container')
+      assert.equal(result[0]!.children![0]!.overridden, true)
+    })
+  })
+
+  // ─── Built-in elements ──────────────────────────────────
+
+  describe('built-in elements', () => {
+    it('resolves Text leaf', async () => {
+      const result = await resolveSchema([Text.make('hello')])
+      assert.deepEqual(result, [{ type: 'text', content: 'hello' }])
+    })
+
+    it('resolves Heading leaf with options', async () => {
+      const result = await resolveSchema([
+        Heading.make('Title').level(2).description('subtitle'),
+      ])
+      assert.deepEqual(result, [{
+        type: 'heading',
+        content: 'Title',
+        level: 2,
+        description: 'subtitle',
+      }])
+    })
+
+    it('resolves Card with children via the schema() builder', async () => {
+      const tree = [
+        Card.make('Stats').schema([
+          Text.make('inside the card'),
+        ]),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!.type, 'card')
+      assert.equal(result[0]!.title, 'Stats')
+      assert.equal(result[0]!.children?.length, 1)
+      assert.deepEqual(result[0]!.children![0], { type: 'text', content: 'inside the card' })
+    })
+
+    it('mixes built-in container with custom leaf via children', async () => {
+      const tree = [
+        Card.make('Mixed').schema([
+          Heading.make('h'),
+          new TestLeaf('test-leaf-inside'),
+        ]),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!.children?.length, 2)
+      assert.equal(result[0]!.children![0]!.type, 'heading')
+      assert.equal(result[0]!.children![1]!.type, 'test-leaf')
+    })
+  })
+
+  // ─── Type discriminator guarantee ───────────────────────
+
+  describe('type field guarantee', () => {
+    it('forces meta.type to match getType() even if toMeta forgets to set it', async () => {
+      class ForgetfulLeaf extends Element {
+        getType() { return 'forgetful' }
+        toMeta() { return { someField: 'value' } as Record<string, unknown> }
+      }
+      const result = await resolveSchema([new ForgetfulLeaf()])
+      assert.equal(result[0]!.type, 'forgetful')
+    })
+  })
+
+  // ─── Plan #8 layout-level visibility ────────────────────
+
+  describe('layout-level visibility (Plan #8)', () => {
+    it('drops a layout element when visible(false)', async () => {
+      const tree = [new TestLeaf('a').visible(false), new TestLeaf('b')]
+      const result = await resolveSchema(tree)
+      assert.equal(result.length, 1)
+      assert.equal(result[0]!.label, 'b')
+    })
+
+    it('keeps a layout element when visible(true)', async () => {
+      const tree = [new TestLeaf('keep').visible(true)]
+      const result = await resolveSchema(tree)
+      assert.equal(result.length, 1)
+    })
+
+    it('evaluates visible(fn) against the resolve ctx', async () => {
+      const tree = [
+        new TestLeaf('shown').visible(({ values }) => values?.['kind'] === 'a'),
+        new TestLeaf('hidden').visible(({ values }) => values?.['kind'] === 'b'),
+      ]
+      const result = await resolveSchema(tree, { values: { kind: 'a' } })
+      assert.equal(result.length, 1)
+      assert.equal(result[0]!.label, 'shown')
+    })
+
+    it('awaits async visible() callbacks', async () => {
+      const tree = [
+        new TestLeaf('async').visible(async () => true),
+        new TestLeaf('asyncHidden').visible(async () => false),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result.length, 1)
+      assert.equal(result[0]!.label, 'async')
+    })
+
+    it('hidden(true) drops the element', async () => {
+      const tree = [new TestLeaf('a').hidden(true), new TestLeaf('b')]
+      const result = await resolveSchema(tree)
+      assert.equal(result.length, 1)
+      assert.equal(result[0]!.label, 'b')
+    })
+
+    it('hidden(fn) inverts the predicate', async () => {
+      const tree = [
+        new TestLeaf('shown').hidden(({ values }) => values?.['kind'] === 'b'),
+        new TestLeaf('hidden').hidden(({ values }) => values?.['kind'] === 'a'),
+      ]
+      const result = await resolveSchema(tree, { values: { kind: 'a' } })
+      assert.equal(result.length, 1)
+      assert.equal(result[0]!.label, 'shown')
+    })
+
+    it('throwing visible() callbacks fail closed (treated as hidden)', async () => {
+      const original = console.warn
+      const calls: unknown[] = []
+      console.warn = (...args: unknown[]) => calls.push(args)
+      try {
+        const tree = [
+          new TestLeaf('a').visible(() => { throw new Error('boom') }),
+          new TestLeaf('b'),
+        ]
+        const result = await resolveSchema(tree)
+        assert.equal(result.length, 1)
+        assert.equal(result[0]!.label, 'b')
+        assert.equal(calls.length, 1)
+      } finally {
+        console.warn = original
+      }
+    })
+
+    it('drops hidden containers without recursing into their children', async () => {
+      let leafResolved = false
+      class Tracker extends Element {
+        getType() { return 'tracker' }
+        toMeta() { leafResolved = true; return { type: 'tracker' } }
+      }
+      const tree = [new TestContainer([new Tracker()]).visible(false)]
+      const result = await resolveSchema(tree)
+      assert.equal(result.length, 0)
+      assert.equal(leafResolved, false)
+    })
+  })
+
+  // ─── Plan #8 layout positioning ─────────────────────────
+
+  describe('layout positioning (Plan #8)', () => {
+    it('emits _layout.columnSpan when set', async () => {
+      const tree = [new TestLeaf('a').columnSpan(2)]
+      const result = await resolveSchema(tree)
+      assert.deepEqual(result[0]!._layout, { columnSpan: 2 })
+    })
+
+    it('emits _layout with columnStart and columnOrder when set', async () => {
+      const tree = [new TestLeaf('a').columnStart(2).columnOrder(3)]
+      const result = await resolveSchema(tree)
+      assert.deepEqual(result[0]!._layout, { columnStart: 2, columnOrder: 3 })
+    })
+
+    it('combines all three positioning hints', async () => {
+      const tree = [new TestLeaf('a').columnSpan(3).columnStart(1).columnOrder(2)]
+      const result = await resolveSchema(tree)
+      assert.deepEqual(result[0]!._layout, {
+        columnSpan: 3,
+        columnStart: 1,
+        columnOrder: 2,
+      })
+    })
+
+    it('omits _layout when no positioning method was used', async () => {
+      const tree = [new TestLeaf('a')]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!._layout, undefined)
+    })
+  })
+})