Merge pull request #909 from nextcloud-libraries/backport/fix-docs

docs: Fix typedoc generation and improve documentation of exported member

README.md

@@ -17,15 +17,21 @@ For `nextcloud/vue` version 8 (Nextcloud 28+) see version 5 of this package.
 
 ## Usage
 
+### General
+The styles for the components (Toasts and FilePicker) are provided in the `style.css` file.
+So make sure that the  `@nextcloud/dialogs/style.css` file is included in your app to make sure that the toasts or FilePicker have a proper styling applied.
+
+```js
+import '@nextcloud/dialogs/style.css'
+```
+
 ### Toasts
 
 ```js
 import { showMessage, showInfo, showSuccess, showWarning, showError } from '@nextcloud/dialogs'
-import '@nextcloud/dialogs/dist/index.css'
+import '@nextcloud/dialogs/style.css'
 ```
 
-Make sure that the  `@nextcloud/dialogs/dist/index.css` file is included in your app to make sure that the toasts have a proper styling applied.
-
 If you using `@nextcloud/dialogs >= 4.0` you don't need any svg or scss loader in you projects anymore.
 
 There are different toast styles available, that are exposed in separate functions:
@@ -44,7 +50,56 @@ There are several options that can be passed in as a second parameter, like the
 showError('This is an error shown without a timeout', { timeout: -1 })
 ```
 
-A full list of available options can be found in the [documentation](https://nextcloud.github.io/nextcloud-dialogs/).
+A full list of available options can be found in the [documentation](https://nextcloud-libraries.github.io/nextcloud-dialogs/).
+
+### FilePicker
+There are two ways to spawn a FilePicker provided by the library:
+
+#### Use the FilePickerBuilder
+This way you do not need to use Vue, but can programatically spawn a FilePicker.
+
+```js
+import { getFilePickerBuilder } from '@nextcloud/dialogs'
+const filepicker = getFilePickerBuilder('Pick plain text files')
+    .addMimeTypeFilter('text/plain')
+    .addButton({
+        label: 'Pick',
+        callback: (nodes) => console.log('Picked', nodes),
+    })
+    .build()
+
+// You get the file nodes by the button callback, but also the pick yields the paths of the picked files
+const paths = await filepicker.pick()
+```
+
+#### Use the Vue component directly
+```vue
+<template>
+  <FilePicker name="Pick some files" :buttons="buttons" />
+</template>
+<script setup lang="ts">
+  import {
+    FilePickerVue as FilePicker,
+    type IFilePickerButton,
+  } from '@nextcloud/dialogs'
+  import type { Node } from '@nextcloud/files'
+  import IconShare from 'vue-material-design-icons/Share.vue'
+
+  const buttons: IFilePickerButton[] = [
+    {
+      label: 'Pick',
+      callback: (nodes: Node[]) => console.log('Picked', nodes),
+      type: 'primary'
+    },
+    {
+      label: 'Share',
+      callback: (nodes: Node[]) => console.log('Share picked files', nodes),
+      type: 'secondary',
+      icon: IconShare,
+    }
+  ]
+</script>
+```
 
 ## Releasing a new version
 

l10n/messages.pot

@@ -78,7 +78,7 @@ msgstr ""
 msgid "Size"
 msgstr ""
 
-#: lib/toast.ts:229
+#: lib/toast.ts:242
 msgid "Undo"
 msgstr ""
 

lib/components/FilePicker/index.ts

@@ -20,10 +20,26 @@
  *
  */
 
-import { defineAsyncComponent, type AsyncComponent } from 'vue'
+import type { AsyncComponent } from 'vue'
 import type { DefaultComputed, DefaultData, DefaultMethods } from 'vue/types/options.js'
+import { defineAsyncComponent } from 'vue'
 
-export type IFilePicker = typeof import('./FilePicker.vue').default
+type IFilePickerProps = (typeof import ('./FilePicker.vue').default)['props']
 
 // Async import for module splitting (treeshaking)
-export const FilePickerVue = defineAsyncComponent(() => import('./FilePicker.vue')) as AsyncComponent<DefaultData<never>, DefaultMethods<never>, DefaultComputed, IFilePicker['props']>
+/**
+ * FilePicker Vue component (implemented as async component)
+ * @example
+ * ```vue
+ * <template>
+ *   <FilePicker name="Select a file" :buttons="buttons" />
+ * </template>
+ * <script setup lang="ts">
+ *   import { FilePickerVue as FilePicker, type IFilePickerButton } from '@nextcloud/dialogs'
+ *   const buttons: IFilePickerButton[] = [{
+ *     label: 'Pick',
+ *     callback: (nodes) => console.log('Picked', nodes)
+ *   }]
+ * </script>
+ */
+export const FilePickerVue = defineAsyncComponent(() => import('./FilePicker.vue')) as AsyncComponent<DefaultData<never>, DefaultMethods<never>, DefaultComputed, IFilePickerProps>

lib/index.ts

@@ -2,6 +2,10 @@ export { FilePicker, FilePickerType, FilePickerBuilder, getFilePickerBuilder } f
 export { TOAST_UNDO_TIMEOUT, TOAST_DEFAULT_TIMEOUT, TOAST_PERMANENT_TIMEOUT } from './toast.js'
 export { TOAST_ARIA_LIVE_OFF, TOAST_ARIA_LIVE_POLITE, TOAST_ARIA_LIVE_ASSERTIVE } from './toast.js'
 export { showMessage, showSuccess, showWarning, showInfo, showError, showUndo } from './toast.js'
+export type { ToastOptions, ToastAriaLive, ToastType } from './toast.js'
 
 export { spawnDialog } from './utils/dialogs.js'
+
 export { FilePickerVue } from './components/FilePicker/index.js'
+export type { IFilePickerButton } from './components/types.js'
+

lib/toast.ts

@@ -27,30 +27,43 @@ import { t } from './utils/l10n.js'
 
 import '../styles/toast.scss'
 
-class ToastType {
-
-	static readonly ERROR = 'toast-error';
-	static readonly WARNING = 'toast-warning';
-	static readonly INFO = 'toast-info';
-	static readonly SUCCESS = 'toast-success';
-	static readonly PERMANENT = 'toast-error';
-	static readonly UNDO = 'toast-undo';
+/**
+ * Enum of available Toast types
+ */
+export enum ToastType {
+	ERROR = 'toast-error',
+	WARNING = 'toast-warning',
+	INFO = 'toast-info',
+	SUCCESS = 'toast-success',
+	PERMANENT = 'toast-error',
+	UNDO = 'toast-undo',
 }
 
+/** @deprecated Use ToastAriaLive.OFF */
 export const TOAST_ARIA_LIVE_OFF = 'off'
+/** @deprecated Use ToastAriaLive.POLITE */
 export const TOAST_ARIA_LIVE_POLITE = 'polite'
+/** @deprecated Use ToastAriaLive.ASSERTIVE */
 export const TOAST_ARIA_LIVE_ASSERTIVE = 'assertive'
 
-enum ToastAriaLive {
+export enum ToastAriaLive {
 	OFF = TOAST_ARIA_LIVE_OFF,
 	POLITE = TOAST_ARIA_LIVE_POLITE,
 	ASSERTIVE = TOAST_ARIA_LIVE_ASSERTIVE,
 }
 
+/** Timeout in ms of a undo toast */
 export const TOAST_UNDO_TIMEOUT = 10000
+/** Default timeout in ms of toasts */
 export const TOAST_DEFAULT_TIMEOUT = 7000
+/** Timeout value to show a toast permanently */
 export const TOAST_PERMANENT_TIMEOUT = -1
 
+/**
+ * Type of a toast
+ * @see https://apvarun.github.io/toastify-js/
+ * @notExported
+ */
 type Toast = ReturnType<typeof Toastify>
 
 export interface ToastOptions {
@@ -103,7 +116,7 @@ export interface ToastOptions {
 /**
  * Show a toast message
  *
- * @param text Message to be shown in the toast, any HTML is removed by default
+ * @param data Message to be shown in the toast, any HTML is removed by default
  * @param options
  */
 export function showMessage(data: string|Node, options?: ToastOptions): Toast {
@@ -206,13 +219,13 @@ export function showSuccess(text: string, options?: ToastOptions): Toast {
  * @param onUndo Function that is called when the undo button is clicked
  * @param options
  */
-export function showUndo(text: string, onUndo: Function, options?: ToastOptions): Toast {
+export function showUndo(text: string, onUndo: (e: MouseEvent) => void, options?: ToastOptions): Toast {
 	// onUndo callback is mandatory
 	if (!(onUndo instanceof Function)) {
 		throw new Error('Please provide a valid onUndo method')
 	}
 
-	let toast
+	let toast: Toast
 
 	options = Object.assign(options || {}, {
 		// force 10 seconds of timeout

package.json

@@ -16,6 +16,10 @@
       "import": "./dist/style.css",
       "require": "./dist/style.css"
     },
+    "./style.css": {
+      "import": "./dist/style.css",
+      "require": "./dist/style.css"
+    },
     "./legacy.js": {
       "types": "./dist/legacy.d.ts",
       "import": "./dist/legacy.mjs",
@@ -24,10 +28,11 @@
   },
   "scripts": {
     "prepare": "npm run build",
-    "build:doc": "typedoc --excludeExternals --out dist/doc lib && touch dist/doc/.nojekyll",
+    "build:doc": "npm run dev && npm run doc",
     "build": "vite --mode production build",
     "dev": "vite --mode development build",
     "dev:watch": "vite --mode development build --watch",
+    "doc": "typedoc --tsconfig tsconfig-typedoc.json --plugin @zamiell/typedoc-plugin-not-exported --out dist/doc dist/index.d.ts && touch dist/doc/.nojekyll",
     "stylelint": "stylelint src",
     "stylelint:fix": "stylelint src --fix",
     "check-types": "tsc --noEmit",
@@ -67,6 +72,7 @@
     "@nextcloud/vite-config": "^1.0.0-beta.18",
     "@types/gettext-parser": "^4.0.2",
     "@vue/tsconfig": "^0.4.0",
+    "@zamiell/typedoc-plugin-not-exported": "^0.2.0",
     "gettext-extractor": "^3.8.0",
     "gettext-parser": "^7.0.1",
     "sass": "^1.65.1",

tsconfig-typedoc.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./dist"
+  },
+  "exclude": [
+    "node_modules",
+    "build"
+  ],
+  "include": [
+    "dist"
+  ]
+}