@magda/external-ui-plugin-sdk 2.2.0-alpha.1

package/README.md

@@ -0,0 +1,15 @@
+### MAGDA External UI Plugin SDK
+
+Magda allows you to build / bundle React UI components with your own logic and supply the customised UI components to Magda at the time of deployment (via [Helm chart config](https://github.com/magda-io/magda/tree/master/deploy/helm/internal-charts/web-server)) to replace the functionality of existing UI components. For those custom built UI components, we call External UI Plugin Components.
+
+For more information of how to create / config External UI Plugin Components, please refer to [magda-plugin-ui-component-examples repo](https://github.com/magda-io/magda-plugin-ui-component-examples).
+
+This SDK at this moment only contains typescript types of all key data structures.
+
+Not all built-in Magda built-in components can be replaced by an External UI Plugin Component.
+
+For the list of replacable components, please refer to exported component types.
+
+### Documentation
+
+SDK document is available from [here](./docs/modules.md).

package/dist/index.d.ts

@@ -0,0 +1,556 @@
+import { ComponentType } from 'react';
+import { History as History_2 } from 'history';
+import { Location as Location_2 } from 'history';
+import { match } from 'react-router-dom';
+
+declare type Access = {
+    location?: string;
+    useStorageApi?: boolean;
+    note?: string;
+};
+
+declare interface CkanExportAspectProperties {
+    status: CkanExportStatus;
+    exportUserId?: string;
+    ckanId?: string;
+    hasCreated: boolean;
+    exportRequired: boolean;
+    exportAttempted: boolean;
+    lastExportAttemptTime?: Date;
+    exportError?: string;
+}
+
+declare interface CkanExportAspectType {
+    [key: string]: CkanExportAspectProperties;
+}
+
+declare type CkanExportStatus = "withdraw" | "retain";
+
+/**
+ * The common properties that all external UI plugins will receive.
+ *
+ * @export
+ * @interface CommonPropsType
+ */
+export declare interface CommonPropsType {
+    /**
+     * Whether or not the user profile loading request is still in progress.
+     *
+     * @type {boolean}
+     * @memberof CommonPropsType
+     */
+    isFetchingWhoAmI: boolean;
+
+    /**
+     * the user profile data including roles, permission & orgUnit information.
+     *
+     * @type {User}
+     * @memberof CommonPropsType
+     */
+    user: User;
+
+    /**
+     * When it's not `null`, this fields contains the error thrown by the user profile loading request
+     */
+    whoAmIError: Error | null;
+
+    /**
+     * The `config` field contains all frontend config data fields.
+     * External UI plugin developer might be interested in `config.extraConfigData` field.
+     * `config.extraConfigData` field serves as an interface to config external UI plugin at deployment time.
+     * External UI plugin related config data can be supplied via [web-server](https://github.com/magda-io/magda/tree/master/deploy/helm/internal-charts/web-server) helm chart.
+     *
+     * @type {ConfigDataType}
+     * @memberof CommonPropsType
+     */
+    config: ConfigDataType;
+
+    /**
+     * The [history object](https://github.com/remix-run/history/blob/v4/docs/Navigation.md) that you can use to control application navigation.
+     * e.g. switch to a new url.
+     *
+     * @type {History<any>}
+     * @memberof CommonPropsType
+     */
+    history: History_2<any>;
+
+    /**
+     * The [location object](https://github.com/remix-run/history/blob/v4/docs/GettingStarted.md#listening) object implements
+     * a subset of [the window.location interface](https://developer.mozilla.org/en-US/docs/Web/API/Location).
+     *
+     * @type {Location<any>}
+     * @memberof CommonPropsType
+     */
+    location: Location_2<any>;
+
+    /**
+     * The match data is about a route at the given path relative to the current location.
+     * It's generated by [react-router](https://v5.reactrouter.com/web/api/match).
+     *
+     * @type {match<any>}
+     * @memberof CommonPropsType
+     */
+    match: match<any>;
+
+    /**
+     * When called, this function will dispatch the `sign out` action to sign the current user out.
+     *
+     * @memberof CommonPropsType
+     */
+    requestSignOut: () => Promise<void>;
+
+    /**
+     * When called, this function will dispatch an action to force the current user profile data to be reloaded / refreshed.
+     * You may only want to call it after you just modified the user's profile.
+     *
+     * @memberof CommonPropsType
+     */
+    requestWhoAmI: () => Promise<void>;
+
+    /**
+     * When called, this function will dispatch an action to make all client side resource items (e.g. header & footer items etc.)
+     * to be reloaded. You may only want to call it after the current user profile changed or any content items have been updated.
+     * You can optionally passing a boolean parameter `noCache` to control the cache behaviour during the loading.
+     * Its default value is `false`.
+     *
+     * @memberof CommonPropsType
+     */
+    fetchContent: (noCache?: boolean) => Promise<void>;
+}
+
+declare type CompatiblePreviews = {
+    map?: boolean;
+    chart?: boolean;
+    table?: boolean;
+    json?: boolean;
+    html?: boolean;
+    text?: boolean;
+    rss?: boolean;
+    google?: boolean;
+};
+
+declare interface ConfigDataType {
+    image?: {
+        pullPolicy?: string;
+        repository?: string;
+        tag?: string;
+    };
+    authApiBaseUrl?: string;
+    baseUrl?: string;
+    authPluginRedirectUrl?: string;
+    baseExternalUrl?: string;
+    uiBaseUrl?: string;
+    showNotificationBanner?: boolean;
+    contentApiBaseUrl?: string;
+    previewMapBaseUrl?: string;
+    indexerApiBaseUrl?: string;
+    registryApiBaseUrl?: string;
+    registryApiReadOnlyBaseUrl?: string;
+    searchApiBaseUrl?: string;
+    correspondenceApiBaseUrl?: string;
+    storageApiBaseUrl?: string;
+    gapiIds?: Array<string>;
+    adminApiBaseUrl?: string;
+    disableAuthenticationFeatures?: boolean;
+    fallbackUrl?: string;
+    featureFlags?: {
+        [id: string]: boolean;
+    };
+    useMagdaStorageByDefault?: boolean;
+    vocabularyApiEndpoints: string[];
+    defaultOrganizationId?: string;
+    defaultContactEmail?: string;
+    custodianOrgLevel: number;
+    automaticPreviewMaxFileSize: number;
+    mandatoryFields: ValidationFieldList;
+    dateConfig?: DateConfig;
+    noManualKeywords?: boolean;
+    noManualThemes?: boolean;
+    datasetThemes?: string[];
+    keywordsBlackList?: string[];
+    openfaasBaseUrl?: string;
+    ckanExportServers: {
+        [ckanServerUrl: string]: boolean;
+    };
+    defaultCkanServer: string;
+    defaultTimeZone?: string;
+    enableCrawlerViews?: boolean;
+    discourseSiteUrl?: string;
+    discourseIntegrationDatasetPage?: boolean;
+    discourseIntegrationDistributionPage?: boolean;
+    externalUIComponents?: string[];
+    externalCssFiles?: string[];
+    homePageUrl?: string;
+    supportExternalTerriaMapV7?: boolean;
+    openInExternalTerriaMapButtonText?: string;
+    openInExternalTerriaMapTargetUrl?: string;
+    extraConfigData?: {
+        // extraConfigData is mainly for config data passing to external UI plugins
+        [key: string]: any;
+    };
+    previewMapFormatPerference?: RawPreviewMapFormatPerferenceItem[];
+    showContactButtonForNoContactPointDataset?: boolean;
+    defaultDatasetBucket?: string;
+    anonymousUserLandingPage?: string;
+    authenticatedUserLandingPage?: string;
+    authStatusRefreshInterval?: number;
+}
+
+/**
+ * Footer copyright config item
+ *
+ * @export
+ * @interface CopyRightItem
+ */
+export declare interface CopyRightItem {
+    href: string;
+    htmlContent: string;
+    logoSrc: string;
+    order: number;
+}
+
+declare type CurrencyData = {
+    status: "CURRENT" | "SUPERSEDED" | "RETIRED";
+    retireReason?: string;
+    supersededBy?: {
+        id?: string[];
+        name?: string;
+    }[];
+};
+
+export declare type DatasetEditButtonComponentPropsType = {
+    dataset: ParsedDataset;
+};
+
+/**
+ * Dataset page `Edit Dataset` button external plugin component type
+ * @category External UI Plugin Component Types
+ */
+export declare type DatasetEditButtonComponentType = ComponentType<
+    DatasetEditButtonComponentPropsType
+>;
+
+export declare type DatasetLikeButtonComponentPropsType = {
+    dataset: ParsedDataset;
+};
+
+/**
+ * Search Result page `Like Button` external plugin component type
+ * Please note: the `Like Button` on search result page is hidden unless a plugin component is supplied.
+ * @category External UI Plugin Component Types
+ */
+export declare type DatasetLikeButtonComponentType = ComponentType<
+    DatasetLikeButtonComponentPropsType
+>;
+
+declare interface DateConfig {
+    dateFormats: string[];
+    dateRegexes: {
+        dateRegex: RegExp;
+        startDateRegex: RegExp;
+        endDateRegex: RegExp;
+    };
+}
+
+export declare type ExtraVisualisationSectionComponentPropsType = {
+    dataset: ParsedDataset;
+    distributionId?: string;
+};
+
+/**
+ * Visualisation Section external plugin component type.
+ * This plugin will be mounted on dataset or distribution page.
+ * More info & example please refer to repo: [magda-ui-plugin-component-dap-thumbnail-viewer](https://github.com/magda-io/magda-ui-plugin-component-dap-thumbnail-viewer)
+ * @category External UI Plugin Component Types
+ */
+export declare type ExtraVisualisationSectionComponentType = ComponentType<
+    ExtraVisualisationSectionComponentPropsType
+>;
+
+declare type FetchError = {
+    title: string;
+    detail: string;
+};
+
+export declare type FooterComponentPropsType = {
+    noTopMargin: boolean;
+    footerMediumNavs: FooterNavLinkGroup[];
+    footerSmallNavs: FooterNavLinkGroup[];
+    footerCopyRightItems: CopyRightItem[];
+};
+
+/**
+ * Footer external plugin component type
+ * @category External UI Plugin Component Types
+ */
+export declare type FooterComponentType = ComponentType<FooterComponentPropsType>;
+
+/**
+ * Footer Navigation Link Config Item
+ *
+ * @export
+ * @interface FooterNavLink
+ */
+export declare interface FooterNavLink {
+    href: string;
+    label: string;
+    order: number;
+}
+
+/**
+ * Footer Navigation Link Group
+ *
+ * @export
+ * @interface FooterNavLinkGroup
+ */
+export declare interface FooterNavLinkGroup {
+    label: string;
+    links: FooterNavLink[];
+    order: number;
+}
+
+export declare interface HeaderComponentProps {
+    headerNavItems: HeaderNavItem[];
+}
+
+/**
+ * Header external plugin component type
+ * @category External UI Plugin Component Types
+ */
+export declare type HeaderComponentType = ComponentType<HeaderComponentProps>;
+
+/**
+ * The type of Header Navigation Item
+ *
+ * @export
+ * @interface HeaderNavItem
+ */
+export declare interface HeaderNavItem {
+    default?: {
+        href: string;
+        label: string;
+        rel?: string;
+        target?: string;
+    };
+    auth?: Record<string, never>;
+    order: number;
+}
+
+declare type OperationRecord = {
+    id: string;
+    uri: string;
+    name: string;
+    description: string;
+    resource_id: string;
+};
+
+declare type OrgUnit = {
+    id: string;
+    name: string;
+    description: string;
+    left?: number;
+    right?: number;
+    create_by?: string;
+    create_time?: string;
+    edit_by?: string;
+    edit_time?: string;
+};
+
+declare type ParsedDataset = {
+    identifier?: string;
+    title: string;
+    accrualPeriodicity?: string;
+    accrualPeriodicityRecurrenceRule?: string;
+    currency?: CurrencyData;
+    issuedDate?: string;
+    updatedDate?: string;
+    landingPage: string;
+    tags: Array<string>;
+    description: string;
+    distributions: Array<ParsedDistribution>;
+    temporalCoverage?: TemporalCoverage;
+    themes: string[];
+    publisher: Publisher;
+    source?: string;
+    linkedDataRating: number;
+    contactPoint: string;
+    error?: FetchError;
+    hasQuality?: boolean;
+    sourceDetails?: any;
+    provenance?: ParsedProvenance;
+    publishingState?: string;
+    spatialCoverageBbox?: any;
+    temporalExtent?: any;
+    accessLevel?: string;
+    informationSecurity?: ParsedInformationSecurity;
+    accessControl?: {
+        ownerId: string;
+        orgUnitId: string;
+        preAuthorisedPermissionIds: string[];
+    };
+    ckanExport?: CkanExportAspectType;
+    access: Access;
+};
+
+declare type ParsedDistribution = {
+    identifier?: string;
+    title: string;
+    description: string;
+    format: string;
+    downloadURL?: string;
+    accessURL?: string;
+    updatedDate?: string;
+    license: string | any;
+    linkActive: boolean;
+    linkStatusAvailable: boolean;
+    isTimeSeries: boolean;
+    chartFields?: any;
+    compatiblePreviews: CompatiblePreviews;
+    accessNotes?: string;
+    visualizationInfo: any;
+    sourceDetails: any;
+    ckanResource: any;
+    publishingState?: string;
+    accessControl?: {
+        ownerId: string;
+        orgUnitId: string;
+        preAuthorisedPermissionIds: string[];
+    };
+    version?: VersionAspectData;
+    byteSize?: number;
+};
+
+declare type ParsedInformationSecurity = {
+    disseminationLimits: string[];
+    classification: string;
+};
+
+declare type ParsedProvenance = {
+    mechanism?: string;
+    sourceSystem?: string;
+    derivedFrom?: string;
+    affiliatedOrganizations?: Record_2[];
+    isOpenData?: boolean;
+};
+
+declare interface PermissionRecord {
+    id: string;
+    name: string;
+    description: string;
+    resource_id: string;
+    user_ownership_constraint: boolean;
+    org_unit_ownership_constraint: boolean;
+    pre_authorised_constraint: boolean;
+    owner_id: string;
+    create_time: string;
+    create_by: string;
+    edit_time: string;
+    edit_by: string;
+}
+
+export declare const PREFIX = "MagdaPluginComponent";
+
+declare type Publisher = {
+    id: string;
+    name: string;
+    message?: string;
+    aspects: {
+        source?: {
+            url: string;
+            type: string;
+        };
+        "organization-details"?: {
+            name: string;
+            title: string;
+            imageUrl: string;
+            description: string;
+        };
+    };
+};
+
+declare interface RawPreviewMapFormatPerferenceItem {
+    format: string;
+    isDataFile?: boolean;
+    urlRegex?: string;
+}
+
+declare type Record_2 = {
+    id: string;
+    name: string;
+    aspects: { [aspectId: string]: any };
+};
+
+declare type Role = {
+    id: string;
+    name: string;
+    description: string;
+    permissionIds: string[];
+};
+
+declare interface RolePermissionRecord extends PermissionRecord {
+    resource_uri: string;
+    operations?: OperationRecord[];
+}
+
+declare type TemporalCoverage = {
+    intervals: {
+        start?: string;
+        end?: string;
+        startIndeterminate?: "unknown" | "now" | "before" | "after";
+        endIndeterminate?: "unknown" | "now" | "before" | "after";
+    }[];
+};
+
+declare type User = {
+    id: string;
+    displayName: string;
+    email: string;
+    photoURL: string;
+    source: string;
+    sourceId?: string;
+    isAdmin: boolean;
+    roles: Role[];
+    permissions: RolePermissionRecord[];
+    orgUnitId?: string;
+    orgUnit?: OrgUnit;
+    managingOrgUnitIds?: string[];
+};
+
+/**
+ * A global module to manage / coordinate validation workflow.
+ * The overall workflow:
+ * - every UI component should attempt to register itself to participant the validation
+ * - ValidationManager will determine whether should get the component involved in the validation process based on config
+ * - UI components are also responsible for
+ *   - Register the component when componentDidMount and de-register itself when componentWillUnmount
+ *     - Supplie functions for updating component's valid / invalid status (see definition of `ValidationItem`)
+ *   - call `onInputFocusOut` when focus is removed from the component
+ *   - `ValidationManager` supplies `useValidation` hook to facilite this process
+ * - `ValidationManager` also provides function like `validateAll` to validate all active components on screen
+ * - To enable `ValidationManager`, `setStateDataGetter` should also be called when the page component is mounted so that `ValidationManager` has access to state data
+ */
+
+/**
+ * A list of field json path (query against [add dataset page state](https://github.com/magda-io/magda/blob/master/magda-web-client/src/Components/Dataset/Add/DatasetAddCommon.ts#L133) that should be validated / Mandatory.
+ * We currently don't use json path here to query any json data.
+ * Use json path as a standard way to name the mandatory field only.
+ * e.g. ["$.dataset.title", "$.distributions[1].license", "$.dataset.defaultLicense"]
+ */
+declare type ValidationFieldList = string[];
+
+declare type VersionAspectData = {
+    currentVersionNumber: number;
+    versions: VersionItem[];
+};
+
+declare type VersionItem = {
+    versionNumber: number;
+    createTime: string;
+    creatorId?: string;
+    description: string;
+    title: string;
+    internalDataFileUrl?: string;
+    eventId?: number;
+};
+
+export { }

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@magda/external-ui-plugin-sdk",
+  "description": "MAGDA external UI plugin SDK",
+  "version": "2.2.0-alpha.1",
+  "scripts": {
+    "prebuild": "rimraf dist tsconfig.tsbuildinfo",
+    "build": "api-extractor run -l",
+    "docs": "which typedoc; if [ $? -eq 1 ]; then echo \"Error: typedoc is required.\";else typedoc;fi",
+    "release": "npm publish || echo \"Skip releasing npm package @magda/external-ui-plugin-sdk.\""
+  },
+  "author": "Jacky Jiang",
+  "license": "Apache-2.0",
+  "main": "",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/magda-io/magda.git",
+    "directory": "packages/external-ui-plugin-sdk"
+  },
+  "devDependencies": {
+    "@magda/web-client": "^2.2.0-alpha.1",
+    "typescript": "~4.2.4"
+  },
+  "peerDependencies": {
+    "@types/react": "^16.8.17",
+    "@types/history": "^4.7.11",
+    "@types/react-router-dom": "^5.3.3"
+  },
+  "magda": {
+    "language": "typescript",
+    "categories": {
+      "npmPackage": true,
+      "useCommonLib": true
+    }
+  },
+  "keywords": [
+    "Magda",
+    "External UI Plugin",
+    "SDK"
+  ],
+  "files": [
+    "dist"
+  ]
+}