Skip to content

Commit

Permalink
docs: Fix typedoc generation and improve documentation of exported me…
Browse files Browse the repository at this point in the history
…mbers

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
  • Loading branch information
susnux committed Aug 17, 2023
1 parent ab8808c commit 360b216
Show file tree
Hide file tree
Showing 8 changed files with 139 additions and 21 deletions.
63 changes: 59 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion l10n/messages.pot
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ msgstr ""
msgid "Size"
msgstr ""

#: lib/toast.ts:229
#: lib/toast.ts:242
msgid "Undo"
msgstr ""

Expand Down
22 changes: 19 additions & 3 deletions lib/components/FilePicker/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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>
4 changes: 4 additions & 0 deletions lib/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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, IFilePickerFilter } from './components/types.js'

37 changes: 25 additions & 12 deletions lib/toast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
10 changes: 10 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 7 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down
14 changes: 14 additions & 0 deletions tsconfig-typedoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./dist"
},
"exclude": [
"node_modules",
"build"
],
"include": [
"dist"
]
}

0 comments on commit 360b216

Please sign in to comment.