@json-layout/vocabulary 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-layout/vocabulary",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Main JSON Layout vocabulary as JSON schemas and Typescript types. Also contains some small utility functions to validate and normalize annotations.",
   "type": "module",
   "exports": {

package/src/components/index.js

@@ -28,6 +28,9 @@ export const standardComponents = [
   {
     name: 'none'
   },
+  {
+    name: 'slot'
+  },
   {
     name: 'section',
     composite: true

package/src/components/types.ts

@@ -19,6 +19,16 @@ export type None = {
     hint?: string | null;
     [k: string]: unknown;
   });
+export type Slot = {
+  comp?: "slot";
+  [k: string]: unknown;
+} & BaseCompObject &
+  (BaseCompObject & {
+    comp: string;
+    label?: string;
+    hint?: string | null;
+    [k: string]: unknown;
+  });
 export type Section = {
   comp?: "section";
   [k: string]: unknown;

package/src/layout-keyword/index.js

@@ -7,6 +7,7 @@ import {ajv} from '../validate.js'
  * @typedef {import('./types.js').PartialChildren} PartialChildren
  * @typedef {import('./types.js').PartialChild} PartialChild
  * @typedef {import('./types.js').PartialChildComposite} PartialChildComposite
+ * @typedef {import('./types.js').PartialChildSlot} PartialChildSlot
  * @typedef {import('./types.js').PartialSwitch} PartialSwitch
  * @typedef {import('./types.js').PartialCompObject} PartialCompObject
  * @typedef {import('./types.js').PartialGetItems} PartialGetItems
@@ -14,6 +15,8 @@ import {ajv} from '../validate.js'
  * @typedef {import('./types.js').PartialExpression} PartialExpression
  * @typedef {import('./types.js').PartialGetItemsObj} PartialGetItemsObj
  * @typedef {import('./types.js').PartialSlotMarkdown} PartialSlotMarkdown
+ * @typedef {import('./types.js').PartialSlotText} PartialSlotText
+ * @typedef {import('./types.js').PartialSlotName} PartialSlotName
  * @typedef {import('./types.js').PartialSlot} PartialSlot
  * @typedef {import('./types.js').PartialSelectItem} PartialSelectItem
  * @typedef {{ errors: any, (layoutKeyword: any): layoutKeyword is LayoutKeyword }} ValidateLayoutKeyword
@@ -40,7 +43,12 @@ export function isPartialChildren (layoutKeyword) {
 
 /** @type {(partialChild: PartialChild) => partialChild is PartialChildComposite} */
 export function isPartialChildComposite (partialChild) {
-  return typeof partialChild !== 'string' && "children" in partialChild
+  return typeof partialChild !== 'string' && 'children' in partialChild
+}
+
+/** @type {(partialChild: PartialChild) => partialChild is PartialChildSlot} */
+export function isPartialChildSlot (partialChild) {
+  return typeof partialChild !== 'string' && ('text' in partialChild || 'markdown' in partialChild || 'name' in partialChild)
 }
 
 /** @type {(layoutKeyword: LayoutKeyword) => layoutKeyword is PartialCompObject} */
@@ -66,4 +74,14 @@ export function isPartialGetItemsFetch (getItems) {
 /** @type {(partialSlot: PartialSlot) => partialSlot is PartialSlotMarkdown} */
 export function isPartialSlotMarkdown (partialSlot) {
   return typeof partialSlot == 'object' && !!/** @type {PartialSlotMarkdown} */(partialSlot).markdown
+}
+
+/** @type {(partialSlot: PartialSlot) => partialSlot is PartialSlotText} */
+export function isPartialSlotText (partialSlot) {
+  return typeof partialSlot == 'object' && !!/** @type {PartialSlotText} */(partialSlot).text
+}
+
+/** @type {(partialSlot: PartialSlot) => partialSlot is PartialSlotName} */
+export function isPartialSlotName (partialSlot) {
+  return typeof partialSlot == 'object' && !!/** @type {PartialSlotName} */(partialSlot).name
 }

package/src/layout-keyword/schema.js

@@ -176,6 +176,14 @@ export default {
         },
         "if": {
           "$ref": "#/$defs/partial-expression"
+        },
+        "slots": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {
+              "$ref": "#/$defs/partial-slot"
+            }
+          }
         }
       }
     },
@@ -208,19 +216,58 @@ export default {
         },
         "if": {
           "$ref": "#/$defs/partial-expression"
+        },
+        "slots": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {
+              "$ref": "#/$defs/partial-slot"
+            }
+          }
         }
       }
     },
+    "partial-child-slot": {
+      "type": "object",
+      "properties": {
+        "cols": {
+          "$ref": "#/$defs/partial-cols"
+        },
+        "if": {
+          "$ref": "#/$defs/partial-expression"
+        }
+      },
+      "oneOf": [
+        {
+          "$ref": "#/$defs/partial-slot-text"
+        },
+        {
+          "$ref": "#/$defs/partial-slot-markdown"
+        },
+        {
+          "$ref": "#/$defs/partial-slot-name"
+        }
+      ]
+    },
     "partial-child": {
       "anyOf": [
         {
           "type": "string"
         },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/partial-child"
+          }
+        },
         {
           "$ref": "#/$defs/partial-child-ref"
         },
         {
           "$ref": "#/$defs/partial-child-composite"
+        },
+        {
+          "$ref": "#/$defs/partial-child-slot"
         }
       ]
     },

package/src/layout-keyword/schema.json

@@ -73,7 +73,13 @@
       "properties": {
         "key": {"type": ["string", "integer"]},
         "cols": {"$ref": "#/$defs/partial-cols"},
-        "if": {"$ref": "#/$defs/partial-expression"}
+        "if": {"$ref": "#/$defs/partial-expression"},
+        "slots": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {"$ref": "#/$defs/partial-slot"}
+          }
+        }
       }
     },
     "partial-child-composite": {
@@ -85,14 +91,34 @@
         "subtitle": {"type": ["string", "null"]},
         "children": {"$ref": "#/$defs/partial-children"},
         "cols": {"$ref": "#/$defs/partial-cols"},
-        "if": {"$ref": "#/$defs/partial-expression"}
+        "if": {"$ref": "#/$defs/partial-expression"},
+        "slots": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {"$ref": "#/$defs/partial-slot"}
+          }
+        }
       }
     },
+    "partial-child-slot": {
+      "type": "object",
+      "properties": {
+        "cols": {"$ref": "#/$defs/partial-cols"},
+        "if": {"$ref": "#/$defs/partial-expression"}
+      },
+      "oneOf": [
+        {"$ref": "#/$defs/partial-slot-text"},
+        {"$ref": "#/$defs/partial-slot-markdown"},
+        {"$ref": "#/$defs/partial-slot-name"}
+      ]
+    },
     "partial-child": {
       "anyOf": [
         {"type": "string"},
+        {"type": "array", "items": {"$ref": "#/$defs/partial-child"}},
         {"$ref": "#/$defs/partial-child-ref"},
-        {"$ref": "#/$defs/partial-child-composite"}
+        {"$ref": "#/$defs/partial-child-composite"},
+        {"$ref": "#/$defs/partial-child-slot"}
       ]
     },
     "partial-children": {

package/src/layout-keyword/types.ts

@@ -12,7 +12,7 @@ export type ComponentName = string;
  * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
  * via the `definition` "partial-child".
  */
-export type PartialChild = string | PartialChildRef | PartialChildComposite;
+export type PartialChild = string | PartialChild[] | PartialChildRef | PartialChildComposite | PartialChildSlot;
 /**
  * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
  * via the `definition` "partial-cols".
@@ -28,6 +28,30 @@ export type PartialColsNumber = number;
  * via the `definition` "partial-expression".
  */
 export type PartialExpression = string | PartialExpressionObj;
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` ".*".
+ *
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` ".*".
+ *
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` ".*".
+ *
+ * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
+ * via the `definition` "partial-slot".
+ */
+export type PartialSlot = string | PartialSlotText | PartialSlotMarkdown | PartialSlotName;
+export type PartialChildSlot = {
+  cols?: PartialCols;
+  if?: PartialExpression;
+  [k: string]: unknown;
+} & PartialChildSlot1;
+/**
+ * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
+ * via the `definition` "partial-child-slot".
+ */
+export type PartialChildSlot1 = PartialSlotText | PartialSlotMarkdown | PartialSlotName;
 /**
  * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
  * via the `definition` "partial-children".
@@ -68,14 +92,6 @@ export type PartialGetItemsObj = {
   | PartialExpressionObj
   | PartialGetItemsFetch
 );
-/**
- * This interface was referenced by `undefined`'s JSON-Schema definition
- * via the `patternProperty` ".*".
- *
- * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
- * via the `definition` "partial-slot".
- */
-export type PartialSlot = string | PartialSlotText | PartialSlotMarkdown | PartialSlotName;
 
 export interface HttpsJsonLayoutGithubIoLayoutKeyword {
   [k: string]: unknown;
@@ -88,6 +104,9 @@ export interface PartialChildRef {
   key: string | number;
   cols?: PartialCols;
   if?: PartialExpression;
+  slots?: {
+    [k: string]: PartialSlot;
+  };
 }
 /**
  * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
@@ -110,6 +129,27 @@ export interface PartialExpressionObj {
   expr: string;
   [k: string]: unknown;
 }
+/**
+ * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
+ * via the `definition` "partial-slot-text".
+ */
+export interface PartialSlotText {
+  text: string;
+}
+/**
+ * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
+ * via the `definition` "partial-slot-markdown".
+ */
+export interface PartialSlotMarkdown {
+  markdown: string;
+}
+/**
+ * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
+ * via the `definition` "partial-slot-name".
+ */
+export interface PartialSlotName {
+  name: string;
+}
 /**
  * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
  * via the `definition` "partial-child-composite".
@@ -121,6 +161,9 @@ export interface PartialChildComposite {
   children: PartialChildren;
   cols?: PartialCols;
   if?: PartialExpression;
+  slots?: {
+    [k: string]: PartialSlot;
+  };
   [k: string]: unknown;
 }
 /**
@@ -173,27 +216,6 @@ export interface PartialGetItemsFetch {
   url: PartialExpression;
   [k: string]: unknown;
 }
-/**
- * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
- * via the `definition` "partial-slot-text".
- */
-export interface PartialSlotText {
-  text: string;
-}
-/**
- * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
- * via the `definition` "partial-slot-markdown".
- */
-export interface PartialSlotMarkdown {
-  markdown: string;
-}
-/**
- * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
- * via the `definition` "partial-slot-name".
- */
-export interface PartialSlotName {
-  name: string;
-}
 /**
  * This interface was referenced by `HttpsJsonLayoutGithubIoLayoutKeyword`'s JSON-Schema
  * via the `definition` "partial-switch".

package/src/normalize.js

@@ -1,4 +1,4 @@
-import { validateLayoutKeyword, isComponentName, isPartialCompObject, isPartialChildren, isPartialSwitch, isPartialGetItemsExpr, isPartialGetItemsObj, isPartialSlotMarkdown, isPartialGetItemsFetch, isPartialChildComposite } from './layout-keyword/index.js'
+import { validateLayoutKeyword, isComponentName, isPartialCompObject, isPartialChildren, isPartialSwitch, isPartialGetItemsExpr, isPartialGetItemsObj, isPartialSlotMarkdown, isPartialGetItemsFetch, isPartialChildComposite, isPartialChildSlot, isPartialSlotText, isPartialSlotName } from './layout-keyword/index.js'
 import { validateNormalizedLayout } from './normalized-layout/index.js'
 import { getComponentValidate } from './validate.js'
 
@@ -66,18 +66,31 @@ function getDefaultChildren (schemaFragment, type) {
 
 /**
  * @param {Children} defaultChildren
- * @param {PartialChildren} [partialChildren]
+ * @param {PartialChildren | undefined} partialChildren
+ * @param {(text: string) => string} markdown
  * @returns {Children}
  */
-function getChildren (defaultChildren, partialChildren) {
+function getChildren (defaultChildren, partialChildren, markdown) {
   if (!partialChildren) return defaultChildren
   let compI = 0
+  let slotI = 0
   return partialChildren.map(partialChild => {
     if (typeof partialChild === 'string') { // simple string/key referencing a known child
       const matchingDefaultChild = defaultChildren.find(c => c.key === partialChild)
       if (!matchingDefaultChild) throw new Error(`unknown child "${partialChild}"`)
       return matchingDefaultChild
+    } else if (Array.isArray(partialChild)) {
+      compI++
+      return {
+        comp: 'section',
+        key: `$comp-${compI}`,
+        children: getChildren(defaultChildren, partialChild, markdown)
+      }
     } else {
+      if ('slots' in partialChild && !isPartialChildSlot(partialChild)) {
+        partialChild.slots = normalizePartialSlots(partialChild.slots, markdown)
+      }
+      if ('cols' in partialChild) partialChild.cols = normalizePartialCols(partialChild.cols)
       if (partialChild.if) partialChild.if = normalizeExpression(partialChild.if)
       if (typeof partialChild.cols === 'number') partialChild.cols = { sm: partialChild.cols }
       if (typeof partialChild.cols === 'object' && partialChild.cols.xs === undefined) partialChild.cols.xs = 12
@@ -85,15 +98,25 @@ function getChildren (defaultChildren, partialChildren) {
         const matchingDefaultChild = defaultChildren.find(c => c.key === partialChild.key)
         if (!matchingDefaultChild) throw new Error(`unknown child "${partialChild.key}"`)
         return /** @type {Child} */ (partialChild)
-      } else { // a composite component definition, not directly related to a known child
+      } else if (isPartialChildSlot(partialChild)) { // a slot defined as a child
+        /** @type {Child} */
+        slotI++
+        return {
+          key: `$slot-${slotI}`,
+          comp: 'slot',
+          cols: normalizePartialCols(partialChild.cols),
+          slots: normalizePartialSlots({ component: partialChild }, markdown)
+        }
+      } else {
         const child = partialChild
         if (isPartialChildComposite(child)) {
+          // a composite component definition, not directly related to a known child
           if (!child.comp) child.comp = 'section'
-          child.children = getChildren(defaultChildren, child.children)
-        }
-        if (!('key' in partialChild)) {
-          child.key = `$comp-${compI}`
-          compI++
+          child.children = getChildren(defaultChildren, child.children, markdown)
+          if (!('key' in partialChild)) {
+            compI++
+            child.key = `$comp-${compI}`
+          }
         }
         return /** @type {Child} */ (child)
       }
@@ -109,6 +132,7 @@ function getChildren (defaultChildren, partialChildren) {
  * @returns {import('./index.js').ComponentName}
  */
 function getDefaultComp (partial, schemaFragment, type, schemaChild) {
+  if (partial.slots?.component) return 'slot'
   const hasSimpleType = type && ['string', 'integer', 'number'].includes(type)
   if (schemaChild === 'oneOf') return 'one-of-select'
   if (schemaChild === 'patternProperties') return 'list'
@@ -191,6 +215,46 @@ function normalizeExpression (expression, defaultType = 'js-eval', defaultDataAl
   else return { pure: defaultPure, type: defaultType, dataAlias: defaultDataAlias, ...expression }
 }
 
+/**
+ * @param {PartialCompObject['slots']} partialSlots
+ * @param {(text: string) => string} markdown
+ * @returns {import('./normalized-layout/types.js').Slots | undefined}
+ */
+function normalizePartialSlots (partialSlots, markdown) {
+  if (!partialSlots) return
+  /** @type {import('./normalized-layout/types.js').Slots} */
+  const slots = {}
+  for (const [name, slot] of Object.entries(partialSlots)) {
+    if (typeof slot === 'string') {
+      if (['before', 'after'].includes(name)) {
+        slots[name] = { markdown: markdown(slot).trim() }
+      } else {
+        slots[name] = { name: slot }
+      }
+    } else if (isPartialSlotText(slot)) {
+      slots[name] = { text: slot.text }
+    } else if (isPartialSlotName(slot)) {
+      slots[name] = { name: slot.name }
+    } else if (isPartialSlotMarkdown(slot)) {
+      slots[name] = { markdown: markdown(slot.markdown).trim() }
+    }
+  }
+  return slots
+}
+
+/**
+ * @param {PartialCompObject['cols']} partialCols
+ * @returns {import('./normalized-layout/types.js').ColsObj | undefined}
+ */
+function normalizePartialCols (partialCols) {
+  if (typeof partialCols === 'number') {
+    return { xs: 12, sm: partialCols }
+  }
+  if (typeof partialCols === 'object') {
+    return { xs: 12, ...partialCols }
+  }
+}
+
 /**
  * @param {SchemaFragment} schemaFragment
  * @returns {import('./index.js').PartialSelectItem[] | null}
@@ -299,7 +363,7 @@ function getCompObject (key, layoutKeyword, schemaFragment, type, nullable, sche
   if (nullable) partial.nullable = nullable
 
   if (component.composite) {
-    const children = getChildren(getDefaultChildren(schemaFragment, type), partial.children)
+    const children = getChildren(getDefaultChildren(schemaFragment, type), partial.children, markdown)
     partial.children = children
     if (!('title' in partial)) {
       if (children.length === 1 && children[0].key === '$patternProperties') {
@@ -311,7 +375,7 @@ function getCompObject (key, layoutKeyword, schemaFragment, type, nullable, sche
   } else if (partial.comp === 'list') {
     if (schemaChild === 'patternProperties') {
       if (!('title' in partial)) {
-        const children = getChildren(getDefaultChildren(schemaFragment, type), partial.children)
+        const children = getChildren(getDefaultChildren(schemaFragment, type), partial.children, markdown)
         if (children.length === 1 && children[0].key === '$patternProperties') {
           partial.title = schemaFragment.title ?? null
         }
@@ -330,7 +394,7 @@ function getCompObject (key, layoutKeyword, schemaFragment, type, nullable, sche
       partial.listEditMode = partial.listEditMode ?? (itemsType === 'object' ? 'inline-single' : 'inline')
       partial.listActions = partial.listActions ?? ['add', 'edit', 'delete', 'duplicate', 'sort']
     }
-  } else {
+  } else if (partial.comp !== 'slot') {
     if (!('label' in partial) && !schemaChild) {
       partial.label = schemaFragment.title ?? ('' + key)
     }
@@ -442,21 +506,7 @@ function getCompObject (key, layoutKeyword, schemaFragment, type, nullable, sche
     partial.format = 'date-time'
   }
 
-  if (partial.slots) {
-    for (const [name, slot] of Object.entries(partial.slots)) {
-      if (typeof slot === 'string') {
-        if (['before', 'after'].includes(name)) {
-          partial.slots[name] = { markdown: slot }
-        } else {
-          partial.slots[name] = { name: slot }
-        }
-      }
-      const slotObj = partial.slots[name]
-      if (isPartialSlotMarkdown(slotObj)) {
-        slotObj.markdown = markdown(slotObj.markdown).trim()
-      }
-    }
-  }
+  if (partial.slots) partial.slots = normalizePartialSlots(partial.slots, markdown)
 
   if (schemaFragment.description) {
     if (component.composite && !!partial.title && useDescription.includes('subtitle')) {
@@ -476,8 +526,7 @@ function getCompObject (key, layoutKeyword, schemaFragment, type, nullable, sche
   if (partial.help) partial.help = markdown(partial.help).trim()
   if (partial.subtitle) partial.subtitle = markdown(partial.subtitle).trim()
 
-  if (typeof partial.cols === 'number') partial.cols = { xs: partial.cols }
-  if (typeof partial.cols === 'object' && partial.cols.xs === undefined) partial.cols.xs = 12
+  if ('cols' in partial) partial.cols = normalizePartialCols(partial.cols)
 
   const validateComponent = getComponentValidate(component)
   if (!validateComponent(partial)) {

package/src/normalized-layout/index.js

@@ -10,7 +10,9 @@ import {ajv} from '../validate.js'
  * @typedef {import('./types.js').GetItemsFetch} GetItemsFetch
  * @typedef {import('./types.js').Child} Child
  * @typedef {import('./types.js').Children} Children
+ * @typedef {import('./types.js').ChildSlot} ChildSlot
  * @typedef {import('./types.js').CompositeCompObject} CompositeCompObject
+ * @typedef {import('./types.js').SlotCompObject} SlotCompObject
  * @typedef {import('./types.js').ItemsBasedCompObject} ItemsBasedCompObject
  * @typedef {import('./types.js').FocusableCompObject} FocusableCompObject
  * @typedef {import('./types.js').GetItems} GetItems
@@ -20,6 +22,7 @@ import {ajv} from '../validate.js'
  * @typedef {import('./types.js').StateNodeOptionsBase} StateNodeOptionsBase
  * @typedef {import('./types.js').StateNodePropsLib} StateNodePropsLib
  * @typedef {import('./types.js').Slot} Slot
+ * @typedef {import('./types.js').Slots} Slots
  * @typedef {{ errors: any, (layoutKeyword: any): layoutKeyword is NormalizedLayout }} ValidateNormalizedLayout
  */
 
@@ -38,8 +41,13 @@ export function isCompObject (layout) {
 }
 
 /** @type {(child: Child) => child is Child & CompositeCompObject} */
-export function childIsCompObject (child) {
-  return 'comp' in child
+export function childIsCompositeCompObject (child) {
+  return 'comp' in child && 'children' in child
+}
+
+/** @type {(child: Child) => child is Child & SlotCompObject} */
+export function childIsSlotCompObject (child) {
+  return 'comp' in child && child.comp === 'slot'
 }
 
 /** @type {(layout: BaseCompObject, components: Record<string, import('../types.js').ComponentInfo>) => layout is CompositeCompObject} */