@lo-tek/interfaces 0.0.0 → 0.38.0

package/manifest/manifest.schema.json

@@ -0,0 +1,586 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lo-tek.sobernetics.no/manifest.schema.json",
+  "title": "The LO-TEK manifest",
+  "description": "What LO-TEK promises: the elements, the classes with their content and parts, the builder functions and the tokens. Generated by interfaces/scripts/generate-manifest.ts from the code, never written by hand.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "version",
+    "elements",
+    "classes",
+    "builders",
+    "tokens"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1,
+      "description": "The shape of the file. Raised only when a reader has to change to understand it."
+    },
+    "version": {
+      "type": "string",
+      "description": "The version of @lo-tek/interfaces the manifest was written from."
+    },
+    "textLanguage": {
+      "type": "string",
+      "description": "The language of the texts the components and stylesheets write themselves. lotek check warns about one of them on a page in another language."
+    },
+    "elements": {
+      "type": "object",
+      "description": "Every <lt-…> element, with the attributes the component reads.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["link", "attributes"],
+        "properties": {
+          "link": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string",
+            "description": "What the element does, in one or two sentences."
+          },
+          "attributes": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/$defs/elementAttribute"
+            }
+          },
+          "parts": {
+            "type": "object",
+            "description": "The parts the element finds in the markup the renderer writes, with the selector it looks for. An empty object when the element creates its own nodes.",
+            "additionalProperties": {
+              "$ref": "#/$defs/part"
+            }
+          },
+          "name": {
+            "$ref": "#/$defs/name"
+          },
+          "texts": {
+            "type": "object",
+            "description": "The texts the element writes itself, by their name in DEFAULT_TEXTS.",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["text", "replacedBy"],
+              "properties": {
+                "text": { "type": "string" },
+                "replacedBy": {
+                  "type": "array",
+                  "description": "The attributes that replace the text. Any one of them is enough.",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "events": {
+            "type": "object",
+            "description": "The events the element dispatches. All of them bubble and cross shadow boundaries. Absent when the element dispatches nothing.",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "detail": {
+                  "type": "object",
+                  "description": "The fields in event.detail with their types. Absent when the event has none.",
+                  "additionalProperties": {
+                    "enum": ["boolean", "string", "number"]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "classes": {
+      "type": "object",
+      "description": "Every lt- class, with the component it belongs to and the attributes it takes.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "component",
+          "title",
+          "description",
+          "link",
+          "content",
+          "attributes"
+        ],
+        "properties": {
+          "component": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "link": {
+            "type": "string"
+          },
+          "content": {
+            "description": "What the element with the class takes as content, in the same words as the parts: \"text\" is text, \"free\" is anything, \"parts\" is only the parts, and \"none\" is no text, like a control.",
+            "enum": ["text", "free", "parts", "none"]
+          },
+          "partOf": {
+            "type": "string",
+            "description": "The class this one is part of, when it is only a part of another component's markup, like lt-card__title in lt-card. The parent has a part that matches it."
+          },
+          "name": {
+            "$ref": "#/$defs/name"
+          },
+          "texts": {
+            "type": "array",
+            "description": "The texts the stylesheet shows on the element with the class and the attribute, and the CSS variable that replaces each.",
+            "items": {
+              "type": "object",
+              "required": ["variable", "text", "attribute"],
+              "properties": {
+                "variable": { "type": "string" },
+                "text": { "type": "string" },
+                "attribute": { "type": "string" },
+                "value": { "type": "string" },
+                "unless": {
+                  "type": "array",
+                  "description": "Attributes that keep the text from showing.",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "parts": {
+            "type": "object",
+            "description": "The parts the markup consists of, for the classes with a fixed structure, with the selector relative to the element with the class. Absent for the classes without one.",
+            "additionalProperties": {
+              "$ref": "#/$defs/part"
+            }
+          },
+          "attributes": {
+            "type": "object",
+            "additionalProperties": {
+              "description": "An attribute with a closed list of values, or a flag, which is on when it is present.",
+              "oneOf": [
+                {
+                  "type": "object",
+                  "required": ["values"],
+                  "properties": {
+                    "values": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "default": {
+                      "description": "The value its absence means.",
+                      "type": "string"
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "What the attribute does, taken from the option in the builder function that writes it."
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "required": ["flag"],
+                  "properties": {
+                    "flag": {
+                      "const": true
+                    },
+                    "description": {
+                      "type": "string",
+                      "description": "What the attribute does, taken from the option in the builder function that writes it."
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "builders": {
+      "type": "array",
+      "description": "Every builder function in lt, with its options and the shape of its result.",
+      "items": {
+        "type": "object",
+        "required": ["name", "options", "returns"],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "required", "type"],
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "required": {
+                  "type": "boolean"
+                },
+                "type": {
+                  "$ref": "#/$defs/optionType"
+                },
+                "description": {
+                  "type": "string",
+                  "description": "What the option does, taken from the comment on the option in the type."
+                }
+              }
+            }
+          },
+          "returns": {
+            "$ref": "#/$defs/returns"
+          },
+          "table": {
+            "description": "When the options act independently: the base set and what each option adds, derived from the results and checked against every builder case. Another language can build the builder function from it alone.",
+            "oneOf": [
+              {
+                "type": "object",
+                "required": ["kind", "table"],
+                "properties": {
+                  "kind": {
+                    "const": "attributes"
+                  },
+                  "table": {
+                    "$ref": "#/$defs/table"
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": ["kind", "fields"],
+                "properties": {
+                  "kind": {
+                    "const": "group"
+                  },
+                  "fields": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "$ref": "#/$defs/table"
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "tokens": {
+      "type": "object",
+      "description": "The tokens a stylesheet outside the package can build on. The colours are given as axes with what they are for, not as values, since a theme can have other values than LO-TEK's own.",
+      "required": [
+        "spacing",
+        "breakpoints",
+        "containers",
+        "colors",
+        "components"
+      ],
+      "properties": {
+        "spacing": {
+          "type": "object",
+          "description": "The spacing scale, name to value.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "breakpoints": {
+          "type": "object",
+          "description": "The breakpoints, name to width.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "containers": {
+          "type": "object",
+          "description": "The container widths, name to width.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "colors": {
+          "type": "object",
+          "required": ["families", "roles", "layers", "tokens"],
+          "properties": {
+            "families": {
+              "type": "object",
+              "description": "The families, with what each is for.",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "roles": {
+              "type": "object",
+              "description": "The roles as they are written in CSS, with what each is for. A colour token is named --lt-color-<family>-<role>.",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "layers": {
+              "type": "object",
+              "description": "The layers only the neutral family has, like --lt-color-neutral-canvas.",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "tokens": {
+              "type": "array",
+              "description": "Every --lt-color-* name the package ships.",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "components": {
+          "type": "object",
+          "description": "The component variables per component, like --lt-button-padding under button, with the default value, that is, the fallback in the stylesheet.",
+          "additionalProperties": {
+            "type": "object",
+            "description": "Variable name to default value.",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "elementAttribute": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": {
+              "enum": ["flag", "text", "number"]
+            },
+            "description": {
+              "type": "string",
+              "description": "What the attribute does."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "values"],
+          "properties": {
+            "type": {
+              "const": "values"
+            },
+            "values": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "description": {
+              "type": "string",
+              "description": "What the attribute does."
+            }
+          }
+        }
+      ]
+    },
+    "optionType": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": {
+              "enum": ["flag", "text", "number", "textList"]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "values"],
+          "properties": {
+            "kind": {
+              "const": "values"
+            },
+            "values": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "returns": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": {
+              "enum": ["attributes", "text"]
+            },
+            "optional": {
+              "type": "boolean"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "values"],
+          "properties": {
+            "kind": {
+              "const": "values"
+            },
+            "values": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "optional": {
+              "type": "boolean"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "of"],
+          "properties": {
+            "kind": {
+              "const": "list"
+            },
+            "of": {
+              "$ref": "#/$defs/returns"
+            },
+            "optional": {
+              "type": "boolean"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "fields"],
+          "properties": {
+            "kind": {
+              "const": "group"
+            },
+            "fields": {
+              "type": "object",
+              "additionalProperties": {
+                "$ref": "#/$defs/returns"
+              }
+            },
+            "optional": {
+              "type": "boolean"
+            }
+          }
+        }
+      ]
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Attribute name to value. Empty text is a boolean attribute that is on, null removes the attribute, and {name} is the value of the option with that name.",
+      "additionalProperties": {
+        "type": ["string", "null"]
+      }
+    },
+    "table": {
+      "type": "object",
+      "required": ["base", "options"],
+      "properties": {
+        "base": {
+          "$ref": "#/$defs/attributes"
+        },
+        "options": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["cases"],
+            "properties": {
+              "cases": {
+                "type": "object",
+                "additionalProperties": {
+                  "$ref": "#/$defs/attributes"
+                }
+              },
+              "template": {
+                "$ref": "#/$defs/attributes"
+              },
+              "empty": {
+                "$ref": "#/$defs/attributes"
+              }
+            }
+          }
+        }
+      }
+    },
+    "part": {
+      "type": "object",
+      "required": ["selector", "description", "content"],
+      "properties": {
+        "selector": {
+          "type": "string",
+          "description": "The CSS selector the element finds the part with, as it is written in the code."
+        },
+        "description": {
+          "type": "string",
+          "description": "What the part is, and how the element recognises it."
+        },
+        "content": {
+          "description": "What the part contains: \"text\" is text, \"free\" is anything, \"parts\" is other parts in the list, and \"none\" is no text: a control, like a <select> with its <option>s, or an element the component fills.",
+          "enum": ["text", "free", "parts", "none"]
+        },
+        "multiple": {
+          "const": true,
+          "description": "The part can appear more than once."
+        },
+        "unique": {
+          "const": true,
+          "description": "A second part of the same kind is an error, not ordinary content. Without the field the rest can be content, like the buttons in a panel. lotek check reports such a part when it appears more than once."
+        },
+        "optional": {
+          "const": true,
+          "description": "The element works without the part."
+        },
+        "stableId": {
+          "const": true,
+          "description": "The part needs an id from the server: the component never writes one."
+        },
+        "name": {
+          "$ref": "#/$defs/name"
+        }
+      },
+      "additionalProperties": false
+    },
+    "name": {
+      "type": "object",
+      "description": "A name LO-TEK demands where WAI-ARIA does not, or one the component gives itself. lotek check reports an element the markup gives no name.",
+      "properties": {
+        "after": {
+          "type": "string",
+          "description": "The part the component points aria-labelledby at when the markup has neither aria-label nor aria-labelledby."
+        },
+        "id": {
+          "const": true,
+          "description": "That part must have an id from the template: the component does not write one."
+        },
+        "component": {
+          "const": true,
+          "description": "The component names it itself, and no rule judges its name in the markup."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}