Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Fix typedoc generation and improve documentation of exported member #909

Merged
merged 1 commit into from
Aug 18, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 } 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"
]
}
Loading