diff --git a/CHANGELOG.md b/CHANGELOG.md index 78821d86bd3..d6d45ebf7d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,9 @@ The types of changes are: - Remove the extra 'white-space: normal' CSS for FidesJS HTML descriptions [#4850](https://github.com/ethyca/fides/pull/4850) - Fixed data map report to display second level names from the taxonomy as primary (bold) label [#4856](https://github.com/ethyca/fides/pull/4856) +### Developer Experience +- Update typedoc-plugin-markdown to 4.0.0 [#4870](https://github.com/ethyca/fides/pull/4870) + ## [2.35.1](https://github.com/ethyca/fides/compare/2.35.0...2.35.1) ### Added diff --git a/clients/fides-js/docs/README.md b/clients/fides-js/docs/README.md index 9eaf5f0a260..f79c10560f6 100644 --- a/clients/fides-js/docs/README.md +++ b/clients/fides-js/docs/README.md @@ -26,9 +26,7 @@ Google Tag Manager, IAB TCF, etc. See [Fides](interfaces/Fides.md) for how to use the `window.Fides` JavaScript API, [FidesOptions](interfaces/FidesOptions.md) for supported options to customize it's behavior, and [FidesEvent](interfaces/FidesEvent.md) for how to use `window.addEventListener(...)` to subscribe to custom Fides events for real-time updates. -## Table of contents - -### Interfaces +## Interfaces - [FidesEvent](interfaces/FidesEvent.md) - [FidesOptions](interfaces/FidesOptions.md) diff --git a/clients/fides-js/docs/interfaces/Fides.md b/clients/fides-js/docs/interfaces/Fides.md index e19580ba6cf..b24627b46f1 100644 --- a/clients/fides-js/docs/interfaces/Fides.md +++ b/clients/fides-js/docs/interfaces/Fides.md @@ -14,7 +14,7 @@ the `Fides` object is available. Therefore, your code should check for the existence of Fides *or* subscribe to the global `FidesInitialized` event (see [FidesEvent](FidesEvent.md)) for details) before using the `Fides` object in your own code. -**`Example`** +## Example ```html @@ -32,24 +32,11 @@ existence of Fides *or* subscribe to the global `FidesInitialized` event (see ``` -## Table of contents - -### Properties - -- [consent](Fides.md#consent) -- [fides\_string](Fides.md#fides_string) -- [initialized](Fides.md#initialized) -- [getModalLinkLabel](Fides.md#getmodallinklabel) -- [showModal](Fides.md#showmodal) -- [gtm](Fides.md#gtm) -- [init](Fides.md#init) -- [reinitialize](Fides.md#reinitialize) - ## Properties ### consent -• **consent**: `Record`\<`string`, `boolean`\> +> **consent**: `Record`\<`string`, `boolean`\> User's current consent preferences, formatted as a key/value object with: - key: the applicable Fides `notice_key` (e.g. `data_sales_and_sharing`, `analytics`) @@ -65,7 +52,7 @@ The specific keys provided in the `Fides.consent` property are determined based on your Fides configuration, and are provided to the browser based on the user's location, property ID, etc. -**`Example`** +#### Example A `Fides.consent` value showing the user has opted-out of data sales & sharing: ```ts @@ -74,7 +61,7 @@ A `Fides.consent` value showing the user has opted-out of data sales & sharing: } ``` -**`Example`** +#### Example A `Fides.consent` value showing the user has opted-in to analytics, but not marketing: ```ts @@ -84,17 +71,17 @@ A `Fides.consent` value showing the user has opted-in to analytics, but not mark } ``` -___ +*** -### fides\_string +### fides\_string? -• `Optional` **fides\_string**: `string` +> `optional` **fides\_string**: `string` User's current consent string(s) combined into a single value. Currently, this is used by FidesJS to store IAB consent strings from various frameworks such as TCF, GPP, and Google's "Additional Consent" string. -**`Example`** +#### Example Example `fides_string` showing a combination of: - IAB TC string: `CPzHq4APzHq4AAMABBENAUEAALAAAEOAAAAAAEAEACACAAAA` @@ -103,11 +90,11 @@ Example `fides_string` showing a combination of: console.log(Fides.fides_string); // CPzHq4APzHq4AAMABBENAUEAALAAAEOAAAAAAEAEACACAAAA,1~61.70 ``` -___ +*** ### initialized -• **initialized**: `boolean` +> **initialized**: `boolean` Whether or not FidesJS has finished initialization and has loaded the current user's experience, consent preferences, etc. @@ -115,18 +102,18 @@ current user's experience, consent preferences, etc. NOTE: To be notified when initialization has completed, you can subscribe to the `FidesInitialized` event. See [FidesEvent](FidesEvent.md) for details. -___ +*** -### getModalLinkLabel +### getModalLinkLabel() -• **getModalLinkLabel**: (`options?`: \{ `disableLocalization`: `boolean` }) => `string` +> **getModalLinkLabel**: (`options`?) => `string` The modal's "Trigger link label" text can be customized, per regulation, for each language defined in the `experience`. Use this function to get the label in the appropriate language for the user's current locale. To always return in the default language only, pass the `disableLocalization` option as `true`. -**`Example`** +#### Example Getting the link text in the user's current locale (eg. Spanish): ```ts @@ -138,7 +125,7 @@ Getting the link text in the default locale to match other links on the page: console.log(Fides.getModalLinkLabel({ disableLocalization: true })); // "Your Privacy Choices" ``` -**`Example`** +#### Example Applying the link text to a custom modal link element: ```html @@ -148,26 +135,22 @@ Applying the link text to a custom modal link element: ``` -#### Type declaration - -▸ (`options?`): `string` +#### Parameters -##### Parameters - -| Name | Type | +| Parameter | Type | | :------ | :------ | -| `options?` | `Object` | -| `options.disableLocalization` | `boolean` | +| `options`? | `object` | +| `options.disableLocalization`? | `boolean` | -##### Returns +#### Returns `string` -___ +*** -### showModal +### showModal() -• **showModal**: () => `void` +> **showModal**: () => `void` Display the FidesJS modal component on the page, if the current user's session (location, property ID, etc.) matches an `experience` with a modal @@ -186,7 +169,7 @@ When not used as a click handler, `Fides.showModal()` can be called programmatically at any time from your own custom JavaScript logic as desired. -**`Example`** +#### Example Showing the FidesJS modal via an `onclick` handler on a custom button element: ```html @@ -214,7 +197,7 @@ Showing/hiding the custom element using the `fides-overlay-modal-link` CSS class } ``` -**`Example`** +#### Example Showing the FidesJS modal programmatically in a JavaScript function: ```ts @@ -226,19 +209,15 @@ function myCustomShowModalFunction() { } ``` -#### Type declaration - -▸ (): `void` - -##### Returns +#### Returns `void` -___ +*** -### gtm +### gtm() -• **gtm**: () => `void` +> **gtm**: () => `void` Enable the Google Tag Manager (GTM) integration. This should be called immediately after FidesJS is included, and once enabled, FidesJS will @@ -248,7 +227,7 @@ they occur, which can then be used to trigger/block tags in GTM based on See the Google Tag Manager tutorial for more: [https://fid.es/configuring-gtm-consent](https://fid.es/configuring-gtm-consent) -**`Example`** +#### Example Enabling the GTM integration in your site's ``: ```html @@ -258,19 +237,15 @@ Enabling the GTM integration in your site's ``: ``` -#### Type declaration - -▸ (): `void` - -##### Returns +#### Returns `void` -___ +*** -### init +### init() -• **init**: (`config`: `any`) => `Promise`\<`void`\> +> **init**: (`config`) => `Promise`\<`void`\> Initializes FidesJS with an initial configuration object. @@ -279,25 +254,21 @@ Fides Cloud will automatically bundle a `Fides.init(...)` call server-side with the appropriate configuration options for the user's session based on their location, property ID, and the matching experience config from Fides. -#### Type declaration - -▸ (`config`): `Promise`\<`void`\> +#### Parameters -##### Parameters - -| Name | Type | +| Parameter | Type | | :------ | :------ | | `config` | `any` | -##### Returns +#### Returns `Promise`\<`void`\> -___ +*** -### reinitialize +### reinitialize() -• **reinitialize**: () => `Promise`\<`void`\> +> **reinitialize**: () => `Promise`\<`void`\> Reinitialize FidesJS with the initial configuration, but taking into account any new overrides such as the `fides_overrides` global or the query params. @@ -307,10 +278,6 @@ want to modify any FidesJS options after initialization - for example, switching between regular/embedded mode with `fides_embed`, overriding the user's language with `fides_locale`, etc. -#### Type declaration - -▸ (): `Promise`\<`void`\> - -##### Returns +#### Returns `Promise`\<`void`\> diff --git a/clients/fides-js/docs/interfaces/FidesEvent.md b/clients/fides-js/docs/interfaces/FidesEvent.md index 46c5f6332c3..2ffb994d0f4 100644 --- a/clients/fides-js/docs/interfaces/FidesEvent.md +++ b/clients/fides-js/docs/interfaces/FidesEvent.md @@ -8,7 +8,7 @@ interface and include a [detail](FidesEvent.md#detail) object with various prope can be used for inspecting current consent preferences, generating analytics, etc. -**`Example`** +## Example ```ts window.addEventListener("FidesUpdated", (evt) => { @@ -54,27 +54,19 @@ preferences in the FidesJS UI but has yet to *save* those changes (i.e. - `FidesModalClosed`: Dispatched whenever the FidesJS modal is closed. -## Hierarchy +## Extends - `CustomEvent` - ↳ **`FidesEvent`** - -## Table of contents - -### Properties - -- [detail](FidesEvent.md#detail) - ## Properties ### detail -• **detail**: `Object` +> **detail**: `object` Event properties passed by FidesJS when dispatched. Depending on the event type, some properties may or may not be set, so most of these are marked as optional. -**`Example`** +#### Example ```ts window.addEventListener("FidesUpdated", (evt) => { @@ -84,16 +76,14 @@ window.addEventListener("FidesUpdated", (evt) => { }); ``` -#### Type declaration - -| Name | Type | Description | +| Member | Type | Description | | :------ | :------ | :------ | | `consent` | `Record`\<`string`, `boolean`\> | User's current consent preferences; see [Fides.consent](Fides.md#consent) for detail. | -| `fides_string?` | `string` | User's current consent string; see [Fides.fides_string](Fides.md#fides_string) for detail. | -| `extraDetails?` | \{ `servingComponent?`: ``"banner"`` \| ``"modal"`` \| ``"tcf_banner"`` \| ``"tcf_overlay"`` ; `consentMethod?`: ``"accept"`` \| ``"reject"`` \| ``"save"`` \| ``"dismiss"`` \| ``"gpc"`` } | Extra event properties, for additional context. | -| `extraDetails.servingComponent?` | ``"banner"`` \| ``"modal"`` \| ``"tcf_banner"`` \| ``"tcf_overlay"`` | Which FidesJS UI component (if any) caused this event. | -| `extraDetails.consentMethod?` | ``"accept"`` \| ``"reject"`` \| ``"save"`` \| ``"dismiss"`` \| ``"gpc"`` | What consent method (if any) caused this event. | +| `fides_string` | `string` | User's current consent string; see [Fides.fides_string](Fides.md#fides_string) for detail. | +| `extraDetails` | `object` | Extra event properties, for additional context. | +| `extraDetails.servingComponent` | `"banner"` \| `"modal"` \| `"tcf_banner"` \| `"tcf_overlay"` | Which FidesJS UI component (if any) caused this event. | +| `extraDetails.consentMethod` | `"accept"` \| `"reject"` \| `"save"` \| `"dismiss"` \| `"gpc"` | What consent method (if any) caused this event. | #### Overrides -CustomEvent.detail +`CustomEvent.detail` diff --git a/clients/fides-js/docs/interfaces/FidesOptions.md b/clients/fides-js/docs/interfaces/FidesOptions.md index cfd59d877bf..5325b366ae4 100644 --- a/clients/fides-js/docs/interfaces/FidesOptions.md +++ b/clients/fides-js/docs/interfaces/FidesOptions.md @@ -20,7 +20,7 @@ order of precedence: 2. Window Object (second priority) 3. Cookie Values (last priority) -**`Example`** +## Example ```html @@ -36,23 +36,11 @@ order of precedence: ``` -## Table of contents - -### Properties - -- [fides\_clear\_cookie](FidesOptions.md#fides_clear_cookie) -- [fides\_disable\_banner](FidesOptions.md#fides_disable_banner) -- [fides\_disable\_save\_api](FidesOptions.md#fides_disable_save_api) -- [fides\_embed](FidesOptions.md#fides_embed) -- [fides\_locale](FidesOptions.md#fides_locale) -- [fides\_string](FidesOptions.md#fides_string) -- [fides\_tcf\_gdpr\_applies](FidesOptions.md#fides_tcf_gdpr_applies) - ## Properties ### fides\_clear\_cookie -• **fides\_clear\_cookie**: `boolean` +> **fides\_clear\_cookie**: `boolean` When `true`, deletes the `fides_consent` cookie when FidesJS is initialized, to clear any previously saved consent preferences from the @@ -60,31 +48,31 @@ user's device. Defaults to `false`. -___ +*** ### fides\_disable\_banner -• **fides\_disable\_banner**: `boolean` +> **fides\_disable\_banner**: `boolean` When `true`, disable the FidesJS banner from being shown. Defaults to `false`. -___ +*** ### fides\_disable\_save\_api -• **fides\_disable\_save\_api**: `boolean` +> **fides\_disable\_save\_api**: `boolean` When `true`, disable FidesJS from saving user consent preferences to the Fides API Defaults to `false`. -___ +*** ### fides\_embed -• **fides\_embed**: `boolean` +> **fides\_embed**: `boolean` When `true`, require FidesJS to "embed" it's UI into a specific `
` on the page, instead of as an overlay over the `` itself. This is useful @@ -102,7 +90,7 @@ FidesJS UI fully from the page! Defaults to `false`. -**`Example`** +#### Example ```html @@ -121,11 +109,11 @@ Defaults to `false`. ``` -___ +*** ### fides\_locale -• **fides\_locale**: `string` +> **fides\_locale**: `string` Override the browser's preferred locale (`navigator.language`) when selecting the best translations for the FidesJS UI. @@ -135,11 +123,11 @@ Must be set to a `string` that is a valid language code (e.g. `"en-US"`, Defaults to `undefined`. -___ +*** ### fides\_string -• **fides\_string**: `string` +> **fides\_string**: `string` Override the current user's `fides_string` consent preferences (see [Fides.fides_string](Fides.md#fides_string)). Can be used to synchronize consent preferences for a registered user from a custom backend, where the `fides_string` could be @@ -148,11 +136,11 @@ selecting the best translations for the FidesJS UI. Defaults to `undefined`. -___ +*** ### fides\_tcf\_gdpr\_applies -• **fides\_tcf\_gdpr\_applies**: `boolean` +> **fides\_tcf\_gdpr\_applies**: `boolean` Override the value for `gdprApplies` set in the IAB TCF CMP API. FidesJS will always default this value to `true` (since the TCF experience will diff --git a/clients/fides-js/package.json b/clients/fides-js/package.json index 13068c7bc1d..d9c95d9a152 100644 --- a/clients/fides-js/package.json +++ b/clients/fides-js/package.json @@ -70,8 +70,9 @@ "rollup-plugin-postcss": "^4.0.2", "rollup-plugin-visualizer": "^5.12.0", "ts-jest": "^29.1.0", + "typedoc": "^0.25.13", + "typedoc-plugin-markdown": "^4.0.0", "typescript": "^4.9.5", - "typedoc-plugin-markdown": "^3.17.1", "typescript-plugin-css-modules": "^5.0.1" }, "typedocOptions": { @@ -81,13 +82,15 @@ "excludePrivate": true, "githubPages": false, "hideBreadcrumbs": true, - "hideInPageTOC": false, + "hidePageHeader": true, "name": "FidesJS: JavaScript SDK for Fides", + "parametersFormat": "table", "plugin": "typedoc-plugin-markdown", "readme": "none", "sort": [ "visibility", "source-order" - ] + ], + "typeDeclarationFormat": "table" } } diff --git a/clients/package-lock.json b/clients/package-lock.json index 4adbdd628e5..fa4126525b0 100644 --- a/clients/package-lock.json +++ b/clients/package-lock.json @@ -183,7 +183,8 @@ "rollup-plugin-postcss": "^4.0.2", "rollup-plugin-visualizer": "^5.12.0", "ts-jest": "^29.1.0", - "typedoc-plugin-markdown": "^3.17.1", + "typedoc": "^0.25.13", + "typedoc-plugin-markdown": "^4.0.0", "typescript": "^4.9.5", "typescript-plugin-css-modules": "^5.0.1" } @@ -6090,8 +6091,7 @@ "version": "1.1.1", "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", - "dev": true, - "peer": true + "dev": true }, "node_modules/ansi-styles": { "version": "3.2.1", @@ -15504,8 +15504,7 @@ "version": "2.3.9", "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", - "dev": true, - "peer": true + "dev": true }, "node_modules/lz-string": { "version": "1.5.0", @@ -15774,7 +15773,6 @@ "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", "dev": true, - "peer": true, "bin": { "marked": "bin/marked.js" }, @@ -20507,7 +20505,6 @@ "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz", "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", "dev": true, - "peer": true, "dependencies": { "ansi-sequence-parser": "^1.1.0", "jsonc-parser": "^3.2.0", @@ -22157,11 +22154,10 @@ } }, "node_modules/typedoc": { - "version": "0.25.12", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.12.tgz", - "integrity": "sha512-F+qhkK2VoTweDXd1c42GS/By2DvI2uDF4/EpG424dTexSHdtCH52C6IcAvMA6jR3DzAWZjHpUOW+E02kyPNUNw==", + "version": "0.25.13", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.13.tgz", + "integrity": "sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==", "dev": true, - "peer": true, "dependencies": { "lunr": "^2.3.9", "marked": "^4.3.0", @@ -22179,15 +22175,12 @@ } }, "node_modules/typedoc-plugin-markdown": { - "version": "3.17.1", - "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-3.17.1.tgz", - "integrity": "sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==", + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-4.0.0.tgz", + "integrity": "sha512-7cNKIGxGq1w9IvwWbm6jAASUCvlJeaANJXCOH+Fcvz2JrNIIMVbRu4j2Nq2zpDDaBHsrUmKVaz+F5vroMU8u4A==", "dev": true, - "dependencies": { - "handlebars": "^4.7.7" - }, "peerDependencies": { - "typedoc": ">=0.24.0" + "typedoc": "0.25.x" } }, "node_modules/typedoc/node_modules/brace-expansion": { @@ -22195,7 +22188,6 @@ "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", "dev": true, - "peer": true, "dependencies": { "balanced-match": "^1.0.0" } @@ -22205,7 +22197,6 @@ "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", "dev": true, - "peer": true, "dependencies": { "brace-expansion": "^2.0.1" }, @@ -22615,15 +22606,13 @@ "version": "1.7.0", "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", - "dev": true, - "peer": true + "dev": true }, "node_modules/vscode-textmate": { "version": "8.0.0", "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", - "dev": true, - "peer": true + "dev": true }, "node_modules/w3c-xmlserializer": { "version": "4.0.0",