@vendure/admin-ui 1.3.2 → 1.4.0

package/core/app.component.d.ts

@@ -12,4 +12,5 @@ export declare class AppComponent implements OnInit {
     private _document?;
     constructor(dataService: DataService, serverConfigService: ServerConfigService, localStorageService: LocalStorageService, document?: any);
     ngOnInit(): void;
+    handleGlobalHotkeys(event: KeyboardEvent): void;
 }

package/core/common/base-detail.component.d.ts

@@ -1,10 +1,50 @@
-import { FormGroup } from '@angular/forms';
+import { AbstractControl, FormGroup } from '@angular/forms';
 import { ActivatedRoute, Router } from '@angular/router';
 import { Observable, Subject } from 'rxjs';
 import { DataService } from '../data/providers/data.service';
 import { ServerConfigService } from '../data/server-config';
 import { DeactivateAware } from './deactivate-aware';
 import { CustomFieldConfig, CustomFields, LanguageCode } from './generated-types';
+import { TranslationOf } from './utilities/find-translation';
+/**
+ * @description
+ * A base class for entity detail views. It should be used in conjunction with the
+ * {@link BaseEntityResolver}.
+ *
+ * @example
+ * ```TypeScript
+ * \@Component({
+ *   selector: 'app-my-entity',
+ *   templateUrl: './my-entity.component.html',
+ *   styleUrls: ['./my-entity.component.scss'],
+ *   changeDetection: ChangeDetectionStrategy.OnPush,
+ * })
+ * export class GlobalSettingsComponent extends BaseDetailComponent<MyEntity.Fragment> implements OnInit {
+ *   detailForm: FormGroup;
+ *
+ *   constructor(
+ *     router: Router,
+ *     route: ActivatedRoute,
+ *     serverConfigService: ServerConfigService,
+ *     protected dataService: DataService,
+ *     private formBuilder: FormBuilder,
+ *   ) {
+ *     super(route, router, serverConfigService, dataService);
+ *     this.detailForm = this.formBuilder.group({
+ *       name: [''],
+ *     });
+ *   }
+ *
+ *   protected setFormValues(entity: MyEntity.Fragment, languageCode: LanguageCode): void {
+ *     this.detailForm.patchValue({
+ *       name: entity.name,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @docsCategory list-detail-views
+ */
 export declare abstract class BaseDetailComponent<Entity extends {
     id: string;
     updatedAt?: string;
@@ -26,6 +66,7 @@ export declare abstract class BaseDetailComponent<Entity extends {
     setLanguage(code: LanguageCode): void;
     canDeactivate(): boolean;
     protected abstract setFormValues(entity: Entity, languageCode: LanguageCode): void;
+    protected setCustomFieldFormValues<T = Entity>(customFields: CustomFieldConfig[], formGroup: AbstractControl | null, entity: T, currentTranslation?: TranslationOf<T>): void;
     protected getCustomFieldConfig(key: Exclude<keyof CustomFields, '__typename'>): CustomFieldConfig[];
     protected setQueryParam(key: string, value: any): void;
 }

package/core/common/base-entity-resolver.d.ts

@@ -6,13 +6,40 @@ export interface EntityResolveData<R> extends ResolveData {
 }
 export declare function createResolveData<T extends BaseEntityResolver<R>, R>(resolver: Type<T>): EntityResolveData<R>;
 /**
+ * @description
  * A base resolver for an entity detail route. Resolves to an observable of the given entity, or a "blank"
- * version if the route id equals "create".
+ * version if the route id equals "create". Should be used together with details views which extend the
+ * {@link BaseDetailComponent}.
+ *
+ * @example
+ * ```TypeScript
+ * \@Injectable({
+ *   providedIn: 'root',
+ * })
+ * export class MyEntityResolver extends BaseEntityResolver<MyEntity.Fragment> {
+ *   constructor(router: Router, dataService: DataService) {
+ *     super(
+ *       router,
+ *       {
+ *         __typename: 'MyEntity',
+ *         id: '',
+ *         createdAt: '',
+ *         updatedAt: '',
+ *         name: '',
+ *       },
+ *       id => dataService.query(GET_MY_ENTITY, { id }).mapStream(data => data.myEntity),
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @docsCategory list-detail-views
  */
 export declare class BaseEntityResolver<T> implements Resolve<Observable<T>> {
     protected router: Router;
     private readonly emptyEntity;
     private entityStream;
     constructor(router: Router, emptyEntity: T, entityStream: (id: string) => Observable<T | null | undefined>);
+    /** @internal */
     resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<Observable<T>>;
 }

package/core/common/base-list.component.d.ts

@@ -9,8 +9,70 @@ export declare type MappingFn<T, R> = (result: R) => {
 };
 export declare type OnPageChangeFn<V> = (skip: number, take: number) => V;
 /**
+ * @description
  * This is a base class which implements the logic required to fetch and manipulate
  * a list of data from a query which returns a PaginatedList type.
+ *
+ * @example
+ * ```TypeScript
+ * \@Component({
+ *   selector: 'my-entity-list',
+ *   templateUrl: './my-entity-list.component.html',
+ *   styleUrls: ['./my-entity-list.component.scss'],
+ *   changeDetection: ChangeDetectionStrategy.OnPush,
+ * })
+ * export class MyEntityListComponent extends BaseListComponent<GetMyEntityList.Query, GetMyEntityList.Items> {
+ *   constructor(
+ *     private dataService: DataService,
+ *     router: Router,
+ *     route: ActivatedRoute,
+ *   ) {
+ *     super(router, route);
+ *     super.setQueryFn(
+ *       (...args: any[]) => this.dataService.query<GetMyEntityList.Query>(GET_MY_ENTITY_LIST),
+ *       data => data.myEntities,
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * The template for the component will typically use the {@link DataTableComponent} to display the results.
+ *
+ * @example
+ * ```HTML
+ * <vdr-action-bar>
+ *   <vdr-ab-right>
+ *     <a class="btn btn-primary" [routerLink]="['./create']" *vdrIfPermissions="['CreateSettings', 'CreateTaxRate']">
+ *       <clr-icon shape="plus"></clr-icon>
+ *       Create new my entity
+ *     </a>
+ *   </vdr-ab-right>
+ * </vdr-action-bar>
+ *
+ * <vdr-data-table
+ *   [items]="items$ | async"
+ *   [itemsPerPage]="itemsPerPage$ | async"
+ *   [totalItems]="totalItems$ | async"
+ *   [currentPage]="currentPage$ | async"
+ *   (pageChange)="setPageNumber($event)"
+ *   (itemsPerPageChange)="setItemsPerPage($event)"
+ * >
+ *   <vdr-dt-column>{{ 'common.name' | translate }}</vdr-dt-column>
+ *   <vdr-dt-column></vdr-dt-column>
+ *   <ng-template let-myEntity="item">
+ *     <td class="left align-middle">{{ myEntity.name }}</td>
+ *     <td class="right align-middle">
+ *       <vdr-table-row-action
+ *         iconShape="edit"
+ *         [label]="'common.edit' | translate"
+ *         [linkTo]="['./', myEntity.id]"
+ *       ></vdr-table-row-action>
+ *     </td>
+ *   </ng-template>
+ * </vdr-data-table>
+ * ```
+ *
+ * @docsCategory list-detail-views
  */
 export declare class BaseListComponent<ResultType, ItemType, VariableType = any> implements OnInit, OnDestroy {
     protected router: Router;
@@ -29,18 +91,30 @@ export declare class BaseListComponent<ResultType, ItemType, VariableType = any>
     private defaults;
     constructor(router: Router, route: ActivatedRoute);
     /**
+     * @description
      * Sets the fetch function for the list being implemented.
      */
     setQueryFn(listQueryFn: ListQueryFn<ResultType>, mappingFn: MappingFn<ItemType, ResultType>, onPageChangeFn?: OnPageChangeFn<VariableType>, defaults?: {
         take: number;
         skip: number;
     }): void;
+    /** @internal */
     ngOnInit(): void;
+    /** @internal */
     ngOnDestroy(): void;
+    /**
+     * @description
+     * Sets the current page number in the url.
+     */
     setPageNumber(page: number): void;
+    /**
+     * @description
+     * Sets the number of items per page in the url.
+     */
     setItemsPerPage(perPage: number): void;
     /**
-     * Re-fetch the current page
+     * @description
+     * Re-fetch the current page of results.
      */
     refresh(): void;
     protected setQueryParam(hash: {

package/core/common/component-registry-types.d.ts

@@ -1,10 +1,56 @@
 import { FormControl } from '@angular/forms';
+/**
+ * @description
+ * This interface should be implemented by any component being used as a custom input. For example,
+ * inputs for custom fields, or for configurable arguments.
+ *
+ * @docsCategory custom-input-components
+ */
 export interface FormInputComponent<C = InputComponentConfig> {
+    /**
+     * @description
+     * Should be set to `true` if this component is designed to handle lists.
+     * If `true` then the formControl value will be an array of all the
+     * values in the list.
+     */
     isListInput?: boolean;
+    /**
+     * @description
+     * This is set by the Admin UI when consuming this component, indicating that the
+     * component should be rendered in a read-only state.
+     */
     readonly: boolean;
+    /**
+     * @description
+     * This controls the actual value of the form item. The current value is available
+     * as `this.formControl.value`, and an Observable stream of value changes is available
+     * as `this.formControl.valueChanges`. To update the value, use `.setValue(val)` and then
+     * `.markAsDirty()`.
+     *
+     * Full documentation can be found in the [Angular docs](https://angular.io/api/forms/FormControl).
+     */
     formControl: FormControl;
+    /**
+     * @description
+     * The `config` property contains the full configuration object of the custom field or configurable argument.
+     */
     config: C;
 }
 export declare type InputComponentConfig = {
     [prop: string]: any;
 };
+/**
+ * @description
+ * The valid locationIds for registering action bar items.
+ *
+ * @docsCategory action-bar
+ */
+export declare type ActionBarLocationId = 'administrator-detail' | 'administrator-list' | 'asset-detail' | 'asset-list' | 'channel-detail' | 'channel-list' | 'collection-detail' | 'collection-list' | 'country-detail' | 'country-list' | 'customer-detail' | 'customer-list' | 'customer-group-list' | 'facet-detail' | 'facet-list' | 'global-setting-detail' | 'system-status' | 'job-list' | 'order-detail' | 'order-list' | 'payment-method-detail' | 'payment-method-list' | 'product-detail' | 'product-list' | 'promotion-detail' | 'promotion-list' | 'role-detail' | 'role-list' | 'shipping-method-detail' | 'shipping-method-list' | 'tax-category-detail' | 'tax-category-list' | 'tax-rate-detail' | 'tax-rate-list' | 'zone-list';
+/**
+ * @description
+ * The valid locations for embedding a {@link CustomDetailComponent}.
+ *
+ * @docsCategory custom-detail-components
+ */
+export declare type CustomDetailComponentLocationId = 'administrator-detail' | 'channel-detail' | 'collection-detail' | 'country-detail' | 'customer-detail' | 'facet-detail' | 'global-settings-detail' | 'order-detail' | 'payment-method-detail' | 'product-detail' | 'promotion-detail' | 'shipping-method-detail' | 'tax-category-detail' | 'tax-rate-detail';
+export declare type UIExtensionLocationId = ActionBarLocationId | CustomDetailComponentLocationId;