@json-layout/vocabulary 0.1.0 → 0.3.0

package/src/normalize.js

@@ -1,5 +1,5 @@
 import { validateLayoutKeyword, isComponentName, isPartialCompObject, isPartialChildren, isPartialSwitch, isPartialGetItemsExpr, isPartialGetItemsObj, isPartialSlotMarkdown, isPartialGetItemsFetch } from './layout-keyword/index.js'
-import { validateNormalizedLayout, normalizedLayoutSchema, isSectionLayout, isCompositeLayout } from './index.js'
+import { validateNormalizedLayout, compositeCompNames } from './normalized-layout/index.js'
 
 /**
  * @typedef {import('./index.js').Child} Child
@@ -13,19 +13,15 @@ import { validateNormalizedLayout, normalizedLayoutSchema, isSectionLayout, isCo
  * @typedef {import("./types.js").SchemaFragment} SchemaFragment
  */
 
-// export type Markdown = (src: string) => string
-
-// this navice implementation is sufficient here, not used very often
-const clone = (/** @type {any} */ obj) => JSON.parse(JSON.stringify(obj))
-
 /**
  * @param {import('./types.js').SchemaFragment} schemaFragment
  * @returns {Children}
  */
 function getDefaultChildren (schemaFragment) {
+  const { type } = getType(schemaFragment)
   /** @type {Children} */
   const children = []
-  if (schemaFragment.type === 'object') {
+  if (type === 'object') {
     if (schemaFragment.properties) {
       for (const key of Object.keys(schemaFragment.properties)) {
         children.push({ key })
@@ -40,7 +36,7 @@ function getDefaultChildren (schemaFragment) {
       children.push({ key: '$oneOf' })
     }
   }
-  if (schemaFragment.type === 'array' && Array.isArray(schemaFragment.items)) {
+  if (type === 'array' && Array.isArray(schemaFragment.items)) {
     for (let i = 0; i < schemaFragment.items.length; i++) {
       children.push({ key: i })
     }
@@ -85,81 +81,69 @@ function getChildren (defaultChildren, partialChildren) {
 }
 
 /**
+ * @param {PartialCompObject} partial
  * @param {SchemaFragment} schemaFragment
- * @param {string} schemaPath
- * @returns {import('./index.js').CompObject}
+ * @param {'oneOf'} [arrayChild]
+ * @returns {import('./index.js').ComponentName}
  */
-function getDefaultCompObject (schemaFragment, schemaPath) {
-  const key = schemaPath.slice(schemaPath.lastIndexOf('/') + 1)
-  if ('const' in schemaFragment) return { comp: 'none' }
-  if (!schemaFragment.type) return { comp: 'none' }
-  if (schemaFragment.type === 'object') {
-    return { comp: 'section', title: schemaFragment.title ?? null, children: getDefaultChildren(schemaFragment) }
+function getDefaultComp (partial, schemaFragment, arrayChild) {
+  const { type } = getType(schemaFragment)
+  const hasSimpleType = ['string', 'integer', 'number'].includes(type)
+  if (arrayChild === 'oneOf') return 'one-of-select'
+  if (hasSimpleType && schemaFragment.enum) return schemaFragment.enum.length > 20 ? 'autocomplete' : 'select'
+  if (hasSimpleType && schemaFragment.oneOf) return schemaFragment.oneOf.length > 20 ? 'autocomplete' : 'select'
+  if (hasSimpleType && schemaFragment.examples) return type === 'string' ? 'combobox' : 'number-combobox'
+  if (hasSimpleType && schemaFragment.anyOf && schemaFragment.anyOf.length && Object.keys(schemaFragment.anyOf[schemaFragment.anyOf.length - 1]).length === 0) {
+    return type === 'string' ? 'combobox' : 'number-combobox'
   }
-  if (schemaFragment.type === 'array') {
-    if (!schemaFragment.items) return { comp: 'none' }
-    if (Array.isArray(schemaFragment.items)) {
-      return { comp: 'section', title: schemaFragment.title ?? null, children: getDefaultChildren(schemaFragment) } // tuples
-    }
-    return {
-      comp: 'list',
-      title: schemaFragment.title ?? key,
-      listEditMode: schemaFragment.items.type === 'object' ? 'inline-single' : 'inline',
-      listActions: ['add', 'edit', 'delete', 'duplicate', 'sort']
+  if (partial.items) return partial.items.length > 20 ? 'autocomplete' : 'select'
+  if (partial.getItems) {
+    if (isPartialGetItemsFetch(partial.getItems)) {
+      if (partial.getItems.qSearchParam) return 'autocomplete'
+      if (typeof partial.getItems.url === 'string' && partial.getItems.url.includes('{q}')) return 'autocomplete'
     }
+    return 'select'
   }
-  const hasSimpleType = ['string', 'integer', 'number'].includes(schemaFragment.type)
-  if (schemaFragment.enum && hasSimpleType) {
-    return {
-      comp: 'select',
-      label: schemaFragment.title ?? key,
-      items: schemaFragment.enum.map((/** @type {string} */ value) => ({ key: value + '', title: value + '', value }))
+  if (type === 'array' && schemaFragment.items) {
+    const hasSimpleTypeItems = ['string', 'integer', 'number'].includes(schemaFragment.items.type)
+    if (hasSimpleTypeItems && (schemaFragment.items.enum || schemaFragment.items.oneOf)) {
+      return (schemaFragment.items.enum || schemaFragment.items.oneOf).length > 20 ? 'autocomplete' : 'select'
     }
-  }
-  if (schemaFragment.oneOf && !(schemaFragment.oneOf.find((/** @type {any} */ oneOfItem) => !('const' in oneOfItem))) && hasSimpleType) {
-    return {
-      comp: 'select',
-      label: schemaFragment.title ?? key,
-      items: schemaFragment.oneOf.map((/** @type {{ const: string; title: any; }} */ oneOfItem) => ({ key: oneOfItem.const + '', title: (oneOfItem.title ?? oneOfItem.const) + '', value: oneOfItem.const }))
+    if (hasSimpleTypeItems && schemaFragment.items.examples) {
+      return schemaFragment.items.type === 'string' ? 'combobox' : 'number-combobox'
     }
-  }
-  if (schemaFragment.type === 'string') {
-    if (schemaFragment.format) {
-      /** @type {CompObject | null} */
-      let formatCompObject = null
-      if (schemaFragment.format === 'date') formatCompObject = { comp: 'date-picker', label: schemaFragment.title ?? key, format: 'date' }
-      if (schemaFragment.format === 'date-time') formatCompObject = { comp: 'date-time-picker', label: schemaFragment.title ?? key }
-      if (schemaFragment.format === 'time') formatCompObject = { comp: 'time-picker', label: schemaFragment.title ?? key }
-      if (formatCompObject) {
-        if ('formatMinimum' in schemaFragment) formatCompObject.min = schemaFragment.formatMinimum
-        if ('formatMaximum' in schemaFragment) formatCompObject.max = schemaFragment.formatMaximum
-        return formatCompObject
-      }
+    if (hasSimpleTypeItems && schemaFragment.items.anyOf && schemaFragment.items.anyOf.length && Object.keys(schemaFragment.items.anyOf[schemaFragment.items.anyOf.length - 1]).length === 0) {
+      return schemaFragment.items.type === 'string' ? 'combobox' : 'number-combobox'
+    }
+    if (hasSimpleTypeItems && !schemaFragment.items.layout && !['date', 'date-time', 'time'].includes(schemaFragment.items.format)) {
+      return schemaFragment.items.type === 'string' ? 'combobox' : 'number-combobox'
     }
-    return { comp: 'text-field', label: schemaFragment.title ?? key }
   }
-  if (schemaFragment.type === 'integer' || schemaFragment.type === 'number') {
-    /** @type {import('./index.js').NumberField} */
-    const compObject = { comp: 'number-field', label: schemaFragment.title ?? key }
-    if (schemaFragment.type === 'integer') compObject.step = 1
-    if ('minimum' in schemaFragment) compObject.min = schemaFragment.minimum
-    if ('maximum' in schemaFragment) compObject.max = schemaFragment.maximum
-    return compObject
+  if (type === 'object') return 'section'
+  if (type === 'array') {
+    if (Array.isArray(schemaFragment.items)) return 'section'
+    else return 'list'
+  }
+  if (type === 'string') {
+    if (schemaFragment.format === 'date') return 'date-picker'
+    if (schemaFragment.format === 'date-time') return 'date-time-picker'
+    if (schemaFragment.format === 'time') return 'time-picker'
+    return 'text-field'
   }
-  if (schemaFragment.type === 'boolean') return { comp: 'checkbox', label: schemaFragment.title ?? key }
-  console.warn(`failed to calculate default layout for schema ${schemaPath}`, schemaFragment)
-  return { comp: 'none' }
+  if (type === 'integer' || type === 'number') return 'number-field'
+  if (type === 'boolean') return 'checkbox'
+  throw new Error('failed to calculate default component for schema fragment')
 }
 
 /**
  * @param {LayoutKeyword} layoutKeyword
- * @returns {PartialCompObject | null}
+ * @returns {PartialCompObject}
  */
 function getPartialCompObject (layoutKeyword) {
   if (isPartialCompObject(layoutKeyword)) return { ...layoutKeyword }
   else if (isComponentName(layoutKeyword)) return { comp: layoutKeyword }
   else if (isPartialChildren(layoutKeyword)) return { children: layoutKeyword }
-  return null
+  return {}
 }
 
 /**
@@ -172,24 +156,151 @@ function normalizeExpression (expression, defaultType = 'js-eval') {
   else return { ...expression, type: expression.type ?? defaultType }
 }
 
+/**
+ * @param {SchemaFragment} schemaFragment
+ * @returns {import('./index.js').PartialSelectItem[] | null}
+ */
+function getItemsFromSchema (schemaFragment) {
+  if (!schemaFragment) return null
+  const { type } = getType(schemaFragment)
+  const hasSimpleType = ['string', 'integer', 'number'].includes(type)
+  if (schemaFragment.enum && hasSimpleType) {
+    return schemaFragment.enum.map((/** @type {string} */ value) => ({ key: value + '', title: value + '', value }))
+  }
+  if (schemaFragment.examples && hasSimpleType) {
+    return schemaFragment.examples.map((/** @type {string} */ value) => ({ key: value + '', title: value + '', value }))
+  }
+  if (schemaFragment.anyOf && hasSimpleType && schemaFragment.anyOf.length && Object.keys(schemaFragment.anyOf[schemaFragment.anyOf.length - 1]).length === 0) {
+    const nonEmptyAnyOf = schemaFragment.anyOf.slice(0, -1)
+    if (!(nonEmptyAnyOf.find((/** @type {any} */ oneOfItem) => !('const' in oneOfItem)))) {
+      return nonEmptyAnyOf.map((/** @type {{ const: string; title: any; }} */ anyOfItem) => ({
+        ...anyOfItem,
+        key: anyOfItem.const + '',
+        title: (anyOfItem.title ?? anyOfItem.const) + '',
+        value: anyOfItem.const
+      }))
+    }
+  }
+  if (schemaFragment.oneOf && hasSimpleType && !(schemaFragment.oneOf.find((/** @type {any} */ oneOfItem) => !('const' in oneOfItem)))) {
+    return schemaFragment.oneOf.map((/** @type {{ const: string; title: any; }} */ oneOfItem) => ({
+      ...oneOfItem,
+      key: oneOfItem.const + '',
+      title: (oneOfItem.title ?? oneOfItem.const) + '',
+      value: oneOfItem.const
+    }))
+  }
+  return null
+}
+
+/**
+ * @param {SchemaFragment} schemaFragment
+ * @returns {{type: string, nullable: boolean}}
+ */
+const getType = (schemaFragment) => {
+  if (Array.isArray(schemaFragment.type) && schemaFragment.type.length === 2 && schemaFragment.type.includes('null')) {
+    const type = schemaFragment.type.find(t => t !== 'null')
+    return { type, nullable: true }
+  }
+  return { type: schemaFragment.type, nullable: false }
+}
+
 /**
  * @param {LayoutKeyword} layoutKeyword
- * @param {CompObject} defaultCompObject
  * @param {SchemaFragment} schemaFragment
+ * @param {string} schemaPath
  * @param {(text: string) => string} markdown
- * @returns {CompObject}
+ * @param {'oneOf'} [arrayChild]
+ * @returns {{normalized: CompObject, errors: string[]}}
  */
-function getCompObject (layoutKeyword, defaultCompObject, schemaFragment, markdown) {
+function getCompObject (layoutKeyword, schemaFragment, schemaPath, markdown, arrayChild) {
+  /** @type {string[]} */
+  const errors = []
+  const key = schemaPath.slice(schemaPath.lastIndexOf('/') + 1)
+
+  const { type, nullable } = getType(schemaFragment)
+
+  if ('const' in schemaFragment) return { normalized: { comp: 'none' }, errors }
+  if (!type) return { normalized: { comp: 'none' }, errors }
+  if (type === 'array' && !schemaFragment.items) return { normalized: { comp: 'none' }, errors }
+
   const partial = getPartialCompObject(layoutKeyword)
-  if (!partial) return defaultCompObject
+
+  // chose the default component for a schema fragment
+  if (!partial.comp) {
+    try {
+      partial.comp = getDefaultComp(partial, schemaFragment, arrayChild)
+    } catch (/** @type {any} */err) {
+      errors.push(err.message)
+      partial.comp = 'none'
+    }
+  }
+  if (partial.comp === 'none') return { normalized: { comp: 'none' }, errors }
+
+  if (nullable) partial.nullable = nullable
+
+  // @ts-ignore
+  if (compositeCompNames.includes(partial.comp)) {
+    partial.title = partial.title ?? schemaFragment.title ?? null
+    partial.children = getChildren(getDefaultChildren(schemaFragment), partial.children)
+  } else if (partial.comp === 'list') {
+    partial.title = partial.title ?? schemaFragment.title ?? key
+    partial.listEditMode = partial.listEditMode ?? (schemaFragment.items.type === 'object' ? 'inline-single' : 'inline')
+    partial.listActions = partial.listActions ?? ['add', 'edit', 'delete', 'duplicate', 'sort']
+  } else {
+    partial.label = partial.label ?? schemaFragment.title ?? key
+  }
+
+  if (['select', 'autocomplete', 'combobox'].includes(partial.comp) && !partial.items) {
+    let items
+    if (type === 'array') {
+      items = getItemsFromSchema(schemaFragment.items)
+      partial.multiple = true
+    } else {
+      items = getItemsFromSchema(schemaFragment)
+    }
+    if (items) {
+      if (partial.getItems && isPartialGetItemsObj(partial.getItems)) {
+        partial.getItems.expr = JSON.stringify(items)
+      } else {
+        partial.getItems = JSON.stringify(items)
+      }
+    }
+  }
+
+  if (['combobox', 'number-combobox'].includes(partial.comp)) {
+    if (type === 'array') {
+      partial.multiple = true
+    }
+  }
+
+  if (partial.comp === 'date-picker') {
+    if (schemaFragment.format === 'date') partial.format = 'date'
+    if (schemaFragment.format === 'date-time') partial.format = 'date-time'
+  }
+
+  if (['date-picker', 'date-time-picker', 'time-picker'].includes(partial.comp)) {
+    if ('formatMinimum' in schemaFragment) partial.min = partial.min ?? schemaFragment.formatMinimum
+    if ('formatMaximum' in schemaFragment) partial.max = partial.max ?? schemaFragment.formatMaximum
+  }
+
+  if (['number-field', 'slider'].includes(partial.comp)) {
+    if (type === 'integer') partial.step = partial.step ?? 1
+    if ('minimum' in schemaFragment) partial.min = partial.min ?? schemaFragment.minimum
+    if ('maximum' in schemaFragment) partial.max = partial.max ?? schemaFragment.maximum
+  }
 
   if (partial.if) partial.if = normalizeExpression(partial.if)
+
+  if (partial.defaultData) partial.defaultData = normalizeExpression(partial.defaultData)
+  if (partial.constData) partial.constData = normalizeExpression(partial.constData)
+
   if (partial.getItems && isPartialGetItemsExpr(partial.getItems)) partial.getItems = normalizeExpression(partial.getItems)
   if (partial.getItems && isPartialGetItemsObj(partial.getItems)) {
-    if (schemaFragment.type === 'object') partial.getItems.returnObjects = true
+    if (type === 'object') partial.getItems.returnObjects = true
     if (partial.getItems.itemTitle) partial.getItems.itemTitle = normalizeExpression(partial.getItems.itemTitle)
     if (partial.getItems.itemKey) partial.getItems.itemKey = normalizeExpression(partial.getItems.itemKey)
     if (partial.getItems.itemValue) partial.getItems.itemValue = normalizeExpression(partial.getItems.itemValue)
+    if (partial.getItems.itemIcon) partial.getItems.itemIcon = normalizeExpression(partial.getItems.itemIcon)
     if (partial.getItems.itemsResults) partial.getItems.itemsResults = normalizeExpression(partial.getItems.itemsResults)
   }
   if (partial.getItems && isPartialGetItemsFetch(partial.getItems)) {
@@ -236,48 +347,70 @@ function getCompObject (layoutKeyword, defaultCompObject, schemaFragment, markdo
     }
   }
 
-  /** @type {any} */
-  const compObject = {}
-  if (partial.comp && defaultCompObject.comp !== partial.comp) {
-    const compProperties = normalizedLayoutSchema.$defs[partial.comp]?.properties
-    if (typeof compProperties === 'object') {
-      for (const key of Object.keys(compProperties).concat(['if', 'help', 'cols', 'props', 'slots', 'options'])) {
-        if (key in defaultCompObject) compObject[key] = defaultCompObject[key]
-        if (key in partial) compObject[key] = partial[key]
-      }
-    }
-  } else {
-    Object.assign(compObject, defaultCompObject, partial)
-  }
+  if (schemaFragment.description && !partial.help) partial.help = schemaFragment.description
+  if (partial.help) partial.help = markdown(partial.help).trim()
 
-  if (isSectionLayout(defaultCompObject) && isCompositeLayout(compObject)) {
-    compObject.children = getChildren((defaultCompObject).children, partial.children)
-  }
-
-  if (compObject.description && !compObject.help) compObject.help = compObject.description
-  if (compObject.help) compObject.help = markdown(compObject.help).trim()
-
-  if (typeof compObject.cols === 'number') compObject.cols = { xs: compObject.cols }
-  if (typeof compObject.cols === 'object' && compObject.cols.xs === undefined) compObject.cols.xs = 12
+  if (typeof partial.cols === 'number') partial.cols = { xs: partial.cols }
+  if (typeof partial.cols === 'object' && partial.cols.xs === undefined) partial.cols.xs = 12
 
-  return compObject
+  return { normalized: /** @type {CompObject} */(partial), errors }
 }
 
 /**
  * @param {LayoutKeyword} layoutKeyword
- * @param {CompObject} defaultCompObject
  * @param {SchemaFragment} schemaFragment
+ * @param {string} schemaPath
  * @param {(text: string) => string} markdown
- * @returns {NormalizedLayout}
+ * @param {'oneOf'} [arrayChild]
+ * @returns {{normalized: NormalizedLayout, errors: string[]}}
  */
-function getNormalizedLayout (layoutKeyword, defaultCompObject, schemaFragment, markdown) {
+function getNormalizedLayout (layoutKeyword, schemaFragment, schemaPath, markdown, arrayChild) {
   if (isPartialSwitch(layoutKeyword)) {
-    const switchCases = layoutKeyword.switch.map(layout => getCompObject(layout, clone(defaultCompObject), schemaFragment, markdown))
-    if (!switchCases.find(switchCase => !switchCase.if)) switchCases.push(clone(defaultCompObject))
-    return { switch: switchCases }
+    /** @type {CompObject[]} */
+    const normalizedSwitchCases = []
+    const errors = []
+    const switchCases = [...layoutKeyword.switch]
+    if (!switchCases.find(s => !s.if)) {
+      switchCases.push({})
+    }
+    for (let i = 0; i < switchCases.length; i++) {
+      const switchCase = switchCases[i]
+      const compObjectResult = getCompObject(switchCase, schemaFragment, schemaPath, markdown, arrayChild)
+      normalizedSwitchCases.push(compObjectResult.normalized)
+      for (const error of compObjectResult.errors) errors.push(`switch ${i} - ${error}`)
+    }
+    return { normalized: { switch: normalizedSwitchCases }, errors: [] }
   } else {
-    return getCompObject(layoutKeyword, defaultCompObject, schemaFragment, markdown)
+    return getCompObject(layoutKeyword, schemaFragment, schemaPath, markdown, arrayChild)
+  }
+}
+
+/**
+ * @param {import('ajv').ErrorObject} error
+ * @param {(error: import('ajv').ErrorObject) => boolean} fn
+ * @returns {boolean}
+ */
+function matchValidationError (error, fn) {
+  if (error.keyword === 'errorMessage') {
+    error = error.params.errors[0]
   }
+  return fn(error)
+}
+
+/**
+ * @param {import('ajv').ErrorObject[]} errors
+ * @returns {string[]}
+ */
+function lighterValidationErrors (errors) {
+  const compositeErrors = errors.filter(e => matchValidationError(e, (e) => e.keyword === 'anyOf' || e.keyword === 'oneOf'))
+  // in case of a anyOf/oneOf error there are some subschemas errors that mostly prevent readability
+  for (const compositeError of compositeErrors) {
+    const explicitError = errors.find(e => matchValidationError(e, (e) => e.instancePath === compositeError.instancePath && e.keyword !== 'type'))
+    if (explicitError) {
+      errors = errors.filter(e => matchValidationError(e, (e) => e.instancePath !== compositeError.instancePath || e.keyword !== 'type'))
+    }
+  }
+  return errors.map(e => e.message ?? e.keyword)
 }
 
 /**
@@ -285,29 +418,30 @@ function getNormalizedLayout (layoutKeyword, defaultCompObject, schemaFragment,
  * @param {string} schemaPath
  * @param {(text: string) => string} markdown
  * @param {'oneOf'} [arrayChild]
- * @returns {NormalizedLayout}
+ * @returns {{layout: NormalizedLayout, errors: string[]}}
  */
 export function normalizeLayoutFragment (schemaFragment, schemaPath, markdown = (src) => src, arrayChild) {
   let layoutKeyword
-  /** @type {CompObject} */
-  let defaultCompObject
   if (arrayChild === 'oneOf') {
     layoutKeyword = schemaFragment.oneOfLayout ?? {}
-    defaultCompObject = { comp: 'one-of-select' } // TODO: default label ?
   } else {
     layoutKeyword = schemaFragment.layout ?? {}
-    defaultCompObject = getDefaultCompObject(schemaFragment, schemaPath)
   }
   if (!validateLayoutKeyword(layoutKeyword)) {
     console.error(`layout keyword validation errors at path ${schemaPath}`, layoutKeyword, validateLayoutKeyword.errors)
-    return defaultCompObject
-    // throw new Error(`invalid layout keyword at path ${schemaPath}`, { cause: validateLayoutKeyword.errors })
+    return {
+      layout: getNormalizedLayout({}, schemaFragment, schemaPath, markdown, arrayChild).normalized,
+      errors: lighterValidationErrors(validateLayoutKeyword.errors)
+    }
   }
-  const normalizedLayout = getNormalizedLayout(layoutKeyword, defaultCompObject, schemaFragment, markdown)
-  if (!validateNormalizedLayout(normalizedLayout)) {
+  const normalizedLayout = getNormalizedLayout(layoutKeyword, schemaFragment, schemaPath, markdown, arrayChild)
+  if (!validateNormalizedLayout(normalizedLayout.normalized)) {
     console.error(`normalized layout validation errors at path ${schemaPath}`, normalizedLayout, validateNormalizedLayout.errors)
-    return defaultCompObject
+    return {
+      layout: getNormalizedLayout({}, schemaFragment, schemaPath, markdown, arrayChild).normalized,
+      errors: lighterValidationErrors(validateNormalizedLayout.errors)
+    }
     // throw new Error(`invalid layout at path ${schemaPath}`, { cause: validateNormalizedLayout.errors })
   }
-  return normalizedLayout
+  return { layout: normalizedLayout.normalized, errors: [] }
 }

package/src/normalized-layout/index.js

@@ -9,6 +9,7 @@ import schema from './schema.js'
  * @typedef {import('./types.js').GetItems} GetItems
  * @typedef {import('./types.js').Expression} Expression
  * @typedef {import('./types.js').Select} Select
+ * @typedef {import('./types.js').Autocomplete} Autocomplete
  * @typedef {import('./types.js').SelectItem} SelectItem
  * @typedef {import('./types.js').SelectItems} SelectItems
  * @typedef {import('./types.js').GetItemsFetch} GetItemsFetch
@@ -29,7 +30,9 @@ import schema from './schema.js'
  * @typedef {import('./types.js').Tabs} Tabs
  * @typedef {import('./types.js').VerticalTabs} VerticalTabs
  * @typedef {import('./types.js').ExpansionPanels} ExpansionPanels
+ * @typedef {import('./types.js').Stepper} Stepper
  * @typedef {import('./types.js').List} List
+ * @typedef {import('./types.js').Combobox} Combobox
  * @typedef {import('./types.js').Cols} Cols
  * @typedef {import('./types.js').ColsObj} ColsObj
  * @typedef {import('./types.js').StateNodeOptions} StateNodeOptions
@@ -61,9 +64,11 @@ export function isSectionLayout (layout) {
   return layout.comp === 'section'
 }
 
+export const compositeCompNames = ['section', 'tabs', 'vertical-tabs', 'expansion-panels', 'stepper']
+
 /** @type {(layout: CompObject) => layout is CompositeCompObject} */
 export function isCompositeLayout (layout) {
-  return ['section', 'tabs', 'vertical-tabs', 'expansion-panels'].includes(layout.comp)
+  return compositeCompNames.includes(layout.comp)
 }
 
 /** @type {(layout: CompObject) => layout is TextField} */
@@ -76,6 +81,16 @@ export function isSelectLayout (layout) {
   return layout.comp === 'select'
 }
 
+/** @type {(layout: CompObject) => layout is CompObject & {autofocus: boolean}} */
+export function isFocusableLayout (layout) {
+  return ['text-field', 'number-field', 'textarea', 'select', 'combobox', 'number-combobox', 'autocomplete', 'markdown'].includes(layout.comp)
+}
+
+/** @type {(layout: CompObject) => layout is Select | Combobox | Autocomplete} */
+export function isItemsLayout (layout) {
+  return layout.comp === 'select' || layout.comp === 'combobox' || layout.comp === 'autocomplete'
+}
+
 /** @type {(getItems: GetItems) => getItems is Expression} */
 export function isGetItemsExpression (getItems) {
   return !!getItems.expr