Merge pull request #578 from umbraco/manual-json-schema

JSON Schema for Extensions

src/Umbraco.Web.UI.Client/libs/extensions-registry/collection-view.models.ts

@@ -6,8 +6,24 @@ export interface ManifestCollectionView extends ManifestElement, ManifestWithCon
 }
 
 export interface MetaCollectionView {
+	/**
+	 * The friendly name of the collection view
+	 */
 	label: string;
+
+	/**
+	 * An icon to represent the collection view
+	 *
+	 * @examples [
+	 *   "umb:box",
+	 *   "umb:grid"
+	 * ]
+	 */
 	icon: string;
+
+	/**
+	 * The URL pathname for this collection view that can be deep linked to by sharing the url
+	 */
 	pathName: string;
 }
 

src/Umbraco.Web.UI.Client/libs/extensions-registry/dashboard.models.ts

@@ -6,10 +6,34 @@ export interface ManifestDashboard extends ManifestElement, ManifestWithConditio
 }
 
 export interface MetaDashboard {
+	/**
+	 * This is the URL path for the dashboard which is used for navigating or deep linking directly to the dashboard
+	 * https://yoursite.com/section/settings/dashboard/my-dashboard-path
+	 *
+	 * @example my-dashboard-path
+	 * @examples [
+	 *  "my-dashboard-path"
+	 * ]
+	 */
 	pathname: string;
+
+	/**
+	 * The displayed name (label) for the tab of the dashboard
+	 */
 	label?: string;
 }
 
 export interface ConditionsDashboard {
+	/**
+	 * An array of section aliases that the dashboard should be available in
+	 *
+	 * @uniqueItems true
+	 * @minItems 1
+	 * @items.examples [
+	 *   "Umb.Section.Content",
+	 *   "Umb.Section.Settings"
+	 * ]
+	 *
+	 */
 	sections: string[];
 }

src/Umbraco.Web.UI.Client/libs/extensions-registry/entity-action.models.ts

@@ -1,5 +1,9 @@
 import type { ManifestElement } from './models';
 
+/**
+ * An action to perform on an entity
+ * For example for content you may wish to create a new document etc
+ */
 export interface ManifestEntityAction extends ManifestElement {
 	type: 'entityAction';
 	meta: MetaEntityAction;
@@ -7,9 +11,38 @@ export interface ManifestEntityAction extends ManifestElement {
 }
 
 export interface MetaEntityAction {
+	/**
+	 * An icon to represent the action to be performed
+	 *
+	 * @examples [
+	 *   "umb:box",
+	 *   "umb:grid"
+	 * ]
+	 */
 	icon?: string;
+
+	/**
+	 * The friendly name of the action to perform
+	 *
+	 * @examples [
+	 *   "Create",
+	 *   "Create Content Template"
+	 * ]
+	 */
 	label: string;
+
+	/**
+	 * @TJS-ignore
+	 */
 	api: any; // create interface
+
+	/**
+	 * The alias for the repsoitory of the entity type this action is for
+	 * such as 'Umb.Repository.Documents'
+	 * @examples [
+	 *   "Umb.Repository.Documents"
+	 * ]
+	 */
 	repositoryAlias: string;
 }
 

src/Umbraco.Web.UI.Client/libs/extensions-registry/entity-bulk-action.models.ts

@@ -1,13 +1,33 @@
 import type { ManifestElement, ManifestWithConditions } from './models';
 
+/**
+ * An action to perform on multiple entities
+ * For example for content you may wish to move one or more documents in bulk
+ */
 export interface ManifestEntityBulkAction extends ManifestElement, ManifestWithConditions<ConditionsEntityBulkAction> {
 	type: 'entityBulkAction';
 	meta: MetaEntityBulkAction;
 }
 
 export interface MetaEntityBulkAction {
+	/**
+	 * A friendly label for the action
+	 */
 	label: string;
+
+	/**
+	 * @TJS-ignore
+	 */
 	api: any; // create interface
+
+	/**
+	 * The alias for the repsoitory of the entity type this action is for
+	 * such as 'Umb.Repository.Documents'
+	 *
+	 * @examples [
+	 *   "Umb.Repository.Documents"
+	 * ]
+	 */
 	repositoryAlias: string;
 }
 

src/Umbraco.Web.UI.Client/libs/extensions-registry/header-app.models.ts

@@ -1,10 +1,15 @@
 import type { ManifestElement } from './models';
 
+/**
+ * Header apps are displayed in the top right corner of the backoffice
+ * The two provided header apps are the search and the user menu
+ */
 export interface ManifestHeaderApp extends ManifestElement {
 	type: 'headerApp';
 	//meta: MetaHeaderApp;
 }
 
+// TODO: Warren these don't seem to be used anywhere
 export interface MetaHeaderApp {
 	pathname: string;
 	label: string;

src/Umbraco.Web.UI.Client/libs/extensions-registry/models.ts

@@ -102,10 +102,31 @@ export type SpecificManifestTypeOrManifestBase<T extends keyof ManifestTypeMap |
 	T extends keyof ManifestTypeMap ? ManifestTypeMap[T] : ManifestBase;
 
 export interface ManifestBase {
+	/**
+	 * The type of extension such as dashboard etc...
+	 */
 	type: string;
+
+	/**
+	 * The alias of the extension, ensure it is unique
+	 */
 	alias: string;
-	kind?: any; // I had to add the optional kind property set to undefined. To make the ManifestTypes recognize the Manifest Kind types. Notice that Kinds has to Omit the kind property when extending.
+
+	/**
+	 * The kind of the extension, used to group extensions together
+	 *
+	 * @examples ["button"]
+	 */
+	kind?: unknown; // I had to add the optional kind property set to undefined. To make the ManifestTypes recognize the Manifest Kind types. Notice that Kinds has to Omit the kind property when extending.
+
+	/**
+	 * The friendly name of the extension
+	 */
 	name: string;
+
+	/**
+	 * Extensions such as dashboards are ordered by weight with lower numbers being first in the list
+	 */
 	weight?: number;
 }
 
@@ -118,17 +139,39 @@ export interface ManifestKind {
 }
 
 export interface ManifestWithConditions<ConditionsType> {
+	/**
+	 * Set the conditions for when the extension should be loaded
+	 */
 	conditions: ConditionsType;
 }
 
 export interface ManifestWithLoader<LoaderReturnType> extends ManifestBase {
+	/**
+	 * @TJS-ignore
+	 */
 	loader?: () => Promise<LoaderReturnType>;
 }
 
+/**
+ * The type of extension such as dashboard etc...
+ */
 export interface ManifestClass<T = unknown> extends ManifestWithLoader<object> {
 	//type: ManifestStandardTypes;
+
+	/**
+	 * The file location of the javascript file to load
+	 * @TJS-required
+	 */
 	js?: string;
+
+	/**
+	 * @TJS-ignore
+	 */
 	className?: string;
+
+	/**
+	 * @TJS-ignore
+	 */
 	class?: ClassConstructor<T>;
 	//loader?: () => Promise<object | HTMLElement>;
 }
@@ -139,10 +182,26 @@ export interface ManifestClassWithClassConstructor extends ManifestClass {
 
 export interface ManifestElement extends ManifestWithLoader<object | HTMLElement> {
 	//type: ManifestStandardTypes;
+
+	/**
+	 * The file location of the javascript file to load
+	 *
+	 * @TJS-require
+	 */
 	js?: string;
+
+	/**
+	 * The HTML web component name to use such as 'my-dashboard'
+	 * Note it is NOT <my-dashboard></my-dashboard> but just the name
+	 */
 	elementName?: string;
+
 	//loader?: () => Promise<object | HTMLElement>;
-	meta?: any;
+
+	/**
+	 * This contains properties specific to the type of extension
+	 */
+	meta?: unknown;
 }
 
 export interface ManifestWithView extends ManifestElement {
@@ -156,22 +215,29 @@ export interface MetaManifestWithView {
 }
 
 export interface ManifestElementWithElementName extends ManifestElement {
+	/**
+	 * The HTML web component name to use such as 'my-dashboard'
+	 * Note it is NOT <my-dashboard></my-dashboard> but just the name
+	 */
 	elementName: string;
 }
 
-// TODO: Remove Custom as it has no purpose currently:
-/*
-export interface ManifestCustom extends ManifestBase {
-	type: 'custom';
-	meta?: unknown;
-}
-*/
-
 export interface ManifestWithMeta extends ManifestBase {
+	/**
+	 * This contains properties specific to the type of extension
+	 */
 	meta: unknown;
 }
 
+/**
+ * This type of extension gives full control and will simply load the specified JS file
+ * You could have custom logic to decide which extensions to load/register by using extensionRegistry
+ */
 export interface ManifestEntrypoint extends ManifestBase {
 	type: 'entrypoint';
+
+	/**
+	 * The file location of the javascript file to load in the backoffice
+	 */
 	js: string;
 }

src/Umbraco.Web.UI.Client/libs/extensions-registry/theme.models.ts

@@ -1,7 +1,17 @@
 import type { ManifestWithLoader } from './models';
 
 // TODO: make or find type for JS Module with default export: Would be nice to support css file directly.
+
+/**
+ * Theme manifest for styling the backoffice of Umbraco such as dark, high contrast etc
+ */
 export interface ManifestTheme extends ManifestWithLoader<string> {
 	type: 'theme';
+
+	/**
+	 * File location of the CSS file of the theme
+	 *
+	 * @examples ["themes/dark.theme.css"]
+	 */
 	css?: string;
 }

src/Umbraco.Web.UI.Client/libs/extensions-registry/umbraco-package.ts

@@ -0,0 +1,28 @@
+import type { ManifestTypes } from './models';
+
+/**
+ * Umbraco package manifest JSON
+ */
+export class UmbracoPackage {
+	/**
+	 * @title The name of the Umbraco package
+	 */
+	name?: string;
+
+	/**
+	 * @title The version of the Umbraco package in the style of semver
+	 * @examples ["0.1.0"]
+	 */
+	version?: string;
+
+	/**
+	 * @title Decides if the package sends telemetry data for collection
+	 * @default true
+	 */
+	allowTelemetry?: boolean;
+
+	/**
+	 * @title An array of Umbraco package manifest types that will be installed
+	 */
+	extensions?: ManifestTypes[];
+}

src/Umbraco.Web.UI.Client/libs/extensions-registry/workspace-action.models.ts

@@ -1,6 +1,5 @@
 import type { InterfaceColor, InterfaceLook } from '@umbraco-ui/uui-base/lib/types/index';
 import type { ManifestElement } from './models';
-import { UmbWorkspaceAction } from '@umbraco-cms/backoffice/workspace';
 import type { ClassConstructor } from '@umbraco-cms/backoffice/models';
 
 export interface ManifestWorkspaceAction extends ManifestElement {
@@ -13,7 +12,7 @@ export interface MetaWorkspaceAction {
 	label?: string; //TODO: Use or implement additional label-key
 	look?: InterfaceLook;
 	color?: InterfaceColor;
-	api: ClassConstructor<UmbWorkspaceAction>;
+	api: ClassConstructor<any>;
 }
 
 export interface ConditionsWorkspaceAction {

src/Umbraco.Web.UI.Client/libs/router/index.ts

@@ -1,4 +1,4 @@
-export type * from 'router-slot/model';
+export * from 'router-slot/model';
 export * from 'router-slot/util';
 export * from './route-location.interface';
 export * from './route.context';