Skip to content

Commit 14aad79

Browse files
justinfagnanijustinfagnani
authored
Allow mixins to describe custom elements (#31)
1 parent df05c2f commit 14aad79

File tree

2 files changed

+235
-55
lines changed

2 files changed

+235
-55
lines changed

‎schema.json‎

Lines changed: 131 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515
"description": "The name of the field this attribute is associated with, if any.",
1616
"type": "string"
1717
},
18+
"inheritedFrom": {
19+
"$ref": "#/definitions/Reference"
20+
},
1821
"name": {
1922
"type": "string"
2023
},
@@ -58,6 +61,7 @@
5861
"type": "array"
5962
},
6063
"mixins": {
64+
"description": "Any class mixins applied in the extends clause of this class.\n\nIf mixins are applied in the class definition, then the true superclass\nof this class is the result of applying mixins in order to the superclass.\n\nMixins must be listed in order of their application to the superclass or\nprevious mixin application. This means that the innermost mixin is listed\nfirst. This may read backwards from the common order in JavaScript, but\nmatches the order of language used to describe mixin application, like\n\"S with A, B\".",
6165
"items": {
6266
"$ref": "#/definitions/Reference"
6367
},
@@ -71,7 +75,8 @@
7175
"type": "string"
7276
},
7377
"superclass": {
74-
"$ref": "#/definitions/Reference"
78+
"$ref": "#/definitions/Reference",
79+
"description": "The superclass of this class.\n\nIf this class is defined with mixin\napplications, the prototype chain includes the mixin applications\nand the true superclass is computed from them."
7580
}
7681
},
7782
"required": [
@@ -216,39 +221,13 @@
216221
],
217222
"type": "object"
218223
},
219-
"CustomElement": {
220-
"description": "Description of a custom element class.\n\nCustom elements are JavaScript classes, so this extends from\n`ClassDeclaration` and adds custom-element-specific features like\nattributes, events, and slots.\n\nNote that `tagName` in this interface is optional. Tag names are not\nneccessarily part of a custom element class, but belong to the definition\n(often called the \"registration\") or the `customElements.define()` call.\n\nBecause classes and tag anmes can only be registered once, there's a\none-to-one relationship between classes and tag names. For ease of use,\nwe allow the tag name here.\n\nSome packages define and register custom elements in separate modules. In\nthese cases one `Module` should contain the `CustomElement` without a\ntagName, and another `Module` should contain the\n`CustomElement`.",
224+
"CustomElementDeclaration": {
225+
"description": "A description of a custom element class.\n\nCustom elements are JavaScript classes, so this extends from\n`ClassDeclaration` and adds custom-element-specific features like\nattributes, events, and slots.\n\nNote that `tagName` in this interface is optional. Tag names are not\nneccessarily part of a custom element class, but belong to the definition\n(often called the \"registration\") or the `customElements.define()` call.\n\nBecause classes and tag anmes can only be registered once, there's a\none-to-one relationship between classes and tag names. For ease of use,\nwe allow the tag name here.\n\nSome packages define and register custom elements in separate modules. In\nthese cases one `Module` should contain the `CustomElement` without a\ntagName, and another `Module` should contain the\n`CustomElement`.",
221226
"properties": {
222-
"attributes": {
223-
"description": "The attributes that this element is known to understand.",
224-
"items": {
225-
"$ref": "#/definitions/Attribute"
226-
},
227-
"type": "array"
228-
},
229-
"cssProperties": {
230-
"items": {
231-
"$ref": "#/definitions/CssCustomProperty"
232-
},
233-
"type": "array"
234-
},
235-
"demos": {
236-
"items": {
237-
"$ref": "#/definitions/Demo"
238-
},
239-
"type": "array"
240-
},
241227
"description": {
242228
"description": "A markdown description of the class.",
243229
"type": "string"
244230
},
245-
"events": {
246-
"description": "The events that this element fires.",
247-
"items": {
248-
"$ref": "#/definitions/Event"
249-
},
250-
"type": "array"
251-
},
252231
"kind": {
253232
"enum": [
254233
"class"
@@ -269,6 +248,7 @@
269248
"type": "array"
270249
},
271250
"mixins": {
251+
"description": "Any class mixins applied in the extends clause of this class.\n\nIf mixins are applied in the class definition, then the true superclass\nof this class is the result of applying mixins in order to the superclass.\n\nMixins must be listed in order of their application to the superclass or\nprevious mixin application. This means that the innermost mixin is listed\nfirst. This may read backwards from the common order in JavaScript, but\nmatches the order of language used to describe mixin application, like\n\"S with A, B\".",
272252
"items": {
273253
"$ref": "#/definitions/Reference"
274254
},
@@ -277,29 +257,13 @@
277257
"name": {
278258
"type": "string"
279259
},
280-
"parts": {
281-
"items": {
282-
"$ref": "#/definitions/CssPart"
283-
},
284-
"type": "array"
285-
},
286-
"slots": {
287-
"description": "The shadow dom content slots that this element accepts.",
288-
"items": {
289-
"$ref": "#/definitions/Slot"
290-
},
291-
"type": "array"
292-
},
293260
"summary": {
294261
"description": "A markdown summary suitable for display in a listing.",
295262
"type": "string"
296263
},
297264
"superclass": {
298-
"$ref": "#/definitions/Reference"
299-
},
300-
"tagName": {
301-
"description": "An optional tag name that should be specified if this is a\nself-registering element.\n\nSelf-registering elements must also include a CustomElementExport\nin the module's exports.",
302-
"type": "string"
265+
"$ref": "#/definitions/Reference",
266+
"description": "The superclass of this class.\n\nIf this class is defined with mixin\napplications, the prototype chain includes the mixin applications\nand the true superclass is computed from them."
303267
}
304268
},
305269
"required": [
@@ -355,6 +319,9 @@
355319
"description": "A markdown description.",
356320
"type": "string"
357321
},
322+
"inheritedFrom": {
323+
"$ref": "#/definitions/Reference"
324+
},
358325
"name": {
359326
"type": "string"
360327
},
@@ -452,11 +419,14 @@
452419
{
453420
"$ref": "#/definitions/FunctionDeclaration"
454421
},
422+
{
423+
"$ref": "#/definitions/MixinDeclaration"
424+
},
455425
{
456426
"$ref": "#/definitions/VariableDeclaration"
457427
},
458428
{
459-
"$ref": "#/definitions/CustomElement"
429+
"$ref": "#/definitions/CustomElementDeclaration"
460430
}
461431
]
462432
},
@@ -501,6 +471,117 @@
501471
],
502472
"type": "object"
503473
},
474+
"MixinDeclaration": {
475+
"description": "A description of a class mixin.\n\nMixins are functions which generate a new subclass of a given superclass.\nThis interfaces describes the class and custom element features that\nare added by the mixin. As such, it extends the CustomElement interface and\nClassLike interface.\n\nSince mixins are functions, it also extends the FunctionLike interface. This\nmeans a mixin is callable, and has parameters and a return type.\n\nThe return type is often hard or impossible to accurately describe in type\nsystems like TypeScript. It requires generics and an `extends` operator\nthat TypeScript lacks. Therefore it's recommended that the return type is\nleft empty. The most common form of a mixin function takes a single\nargument, so consumers of this interface should assume that the return type\nis the single argument subclassed by this declaration.\n\nA mixin should not have a superclass. If a mixins composes other mixins,\nthey should be listed in the `mixins` field.\n\nSee [this article]{@link https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/}\nfor more information on the classmixin pattern in JavaScript.",
476+
"properties": {
477+
"attributes": {
478+
"description": "The attributes that this element is known to understand.",
479+
"items": {
480+
"$ref": "#/definitions/Attribute"
481+
},
482+
"type": "array"
483+
},
484+
"cssParts": {
485+
"items": {
486+
"$ref": "#/definitions/CssPart"
487+
},
488+
"type": "array"
489+
},
490+
"cssProperties": {
491+
"items": {
492+
"$ref": "#/definitions/CssCustomProperty"
493+
},
494+
"type": "array"
495+
},
496+
"demos": {
497+
"items": {
498+
"$ref": "#/definitions/Demo"
499+
},
500+
"type": "array"
501+
},
502+
"description": {
503+
"description": "A markdown description of the class.",
504+
"type": "string"
505+
},
506+
"events": {
507+
"description": "The events that this element fires.",
508+
"items": {
509+
"$ref": "#/definitions/Event"
510+
},
511+
"type": "array"
512+
},
513+
"kind": {
514+
"enum": [
515+
"mixin"
516+
],
517+
"type": "string"
518+
},
519+
"members": {
520+
"items": {
521+
"anyOf": [
522+
{
523+
"$ref": "#/definitions/ClassField"
524+
},
525+
{
526+
"$ref": "#/definitions/ClassMethod"
527+
}
528+
]
529+
},
530+
"type": "array"
531+
},
532+
"mixins": {
533+
"description": "Any class mixins applied in the extends clause of this class.\n\nIf mixins are applied in the class definition, then the true superclass\nof this class is the result of applying mixins in order to the superclass.\n\nMixins must be listed in order of their application to the superclass or\nprevious mixin application. This means that the innermost mixin is listed\nfirst. This may read backwards from the common order in JavaScript, but\nmatches the order of language used to describe mixin application, like\n\"S with A, B\".",
534+
"items": {
535+
"$ref": "#/definitions/Reference"
536+
},
537+
"type": "array"
538+
},
539+
"name": {
540+
"type": "string"
541+
},
542+
"parameters": {
543+
"items": {
544+
"$ref": "#/definitions/Parameter"
545+
},
546+
"type": "array"
547+
},
548+
"return": {
549+
"properties": {
550+
"description": {
551+
"type": "string"
552+
},
553+
"type": {
554+
"$ref": "#/definitions/Type"
555+
}
556+
},
557+
"type": "object"
558+
},
559+
"slots": {
560+
"description": "The shadow dom content slots that this element accepts.",
561+
"items": {
562+
"$ref": "#/definitions/Slot"
563+
},
564+
"type": "array"
565+
},
566+
"summary": {
567+
"description": "A markdown summary suitable for display in a listing.",
568+
"type": "string"
569+
},
570+
"superclass": {
571+
"$ref": "#/definitions/Reference",
572+
"description": "The superclass of this class.\n\nIf this class is defined with mixin\napplications, the prototype chain includes the mixin applications\nand the true superclass is computed from them."
573+
},
574+
"tagName": {
575+
"description": "An optional tag name that should be specified if this is a\nself-registering element.\n\nSelf-registering elements must also include a CustomElementExport\nin the module's exports.",
576+
"type": "string"
577+
}
578+
},
579+
"required": [
580+
"kind",
581+
"name"
582+
],
583+
"type": "object"
584+
},
504585
"Parameter": {
505586
"properties": {
506587
"default": {
@@ -652,7 +733,7 @@
652733
"type": "object"
653734
}
654735
},
655-
"description": "The top-level interface of a custom-elements.json file.\n\nBecause custom elements are JavaScript classes, describing a custom element\nmay require describing arbitrary JavaScript concepts like modules, classes,\nfunctions, etc. So custom-elements.json documents are capable of documenting\nthe elements in a package, as well as those JavaScript concepts.\n\nThe modules described in a package should be the public entrypoints that\nother packages may import from. Multiple modules may export the same object\nvia re-exports, but in most cases a package should document the single\ncanonical export that should be used.",
736+
"description": "The top-level interface of a custom elements manifest file.\n\nBecause custom elements are JavaScript classes, describing a custom element\nmay require describing arbitrary JavaScript concepts like modules, classes,\nfunctions, etc. So custom elements manifests are capable of documenting\nthe elements in a package, as well as those JavaScript concepts.\n\nThe modules described in a package should be the public entrypoints that\nother packages may import from. Multiple modules may export the same object\nvia re-exports, but in most cases a package should document the single\ncanonical export that should be used.",
656737
"properties": {
657738
"modules": {
658739
"description": "An array of the modules this package contains.",
@@ -666,7 +747,7 @@
666747
"type": "string"
667748
},
668749
"schemaVersion": {
669-
"description": "The version of the custom-elements.json schema used in this file.",
750+
"description": "The version of the schema used in this file.",
670751
"type": "string"
671752
}
672753
},

0 commit comments

Comments
 (0)