@schwarzdavid/ui-kit 0.0.1-alpha.16 → 0.0.1-alpha.19

package/README.md

@@ -1,5 +1,165 @@
 # @schwarzdavid/ui-kit
 
-## TODOs
+Vue 3 + Vuetify composables and components for promise-based dialogs, toasts, loading states and translated Vuelidate validators. Dialogs and toasts are created from code with `useDialog()` and `useToast()`, rendered by a single `<UiKitOutlet />`, and settle a Promise when the user closes them.
 
-- Check `useVuelidateErrors` for $each validator
+## Installation
+
+```sh
+npm install @schwarzdavid/ui-kit
+```
+
+The following peer dependencies must be installed in your application:
+
+| Package           | Version                         |
+|-------------------|---------------------------------|
+| `vue`             | `^3.5.0`                        |
+| `vuetify`         | `^3.0.0 \|\| ^4.0.0`            |
+| `vue-i18n`        | `^9.0.0 \|\| ^10.0.0 \|\| ^11.0.0` |
+| `@vuelidate/core` | `^2.0.0`                        |
+
+The package is published as ESM only and has three entry points:
+
+- `@schwarzdavid/ui-kit` for the plugin, the outlet component and the composables
+- `@schwarzdavid/ui-kit/validators` for the translated Vuelidate validators
+- `@schwarzdavid/ui-kit/styles` for the stylesheet
+
+## Setup
+
+1. Register Vuetify, vue-i18n and the ui-kit plugin with `app.use(createUIKit(options))`. All options are optional; see the Configuration page in the docs for the full list and defaults.
+2. Import `@schwarzdavid/ui-kit/styles` once.
+3. Mount `<UiKitOutlet />` once inside `<VApp>`, usually in `App.vue`. It renders every dialog, toast and the loading overlay.
+4. Provide translations for the button labels. By default the dialogs look up `common.yes`, `common.no`, `action.cancel`, `action.close` and `action.save` in the global vue-i18n instance. A key that does not exist is rendered verbatim, so the dialogs still work without translations.
+
+```ts
+import { createApp } from 'vue'
+import { createVuetify } from 'vuetify'
+import { createI18n } from 'vue-i18n'
+import { createUIKit } from '@schwarzdavid/ui-kit'
+import { setGlobalValidationSettings } from '@schwarzdavid/ui-kit/validators'
+import 'vuetify/styles'
+import '@schwarzdavid/ui-kit/styles'
+import App from './App.vue'
+
+const i18n = createI18n({
+    legacy: false,
+    locale: 'en',
+    messages: {
+        en: {
+            common: { yes: 'Yes', no: 'No' },
+            action: { cancel: 'Cancel', close: 'Close', save: 'Save' },
+            validation: { required: 'This field is required' },
+        },
+    },
+})
+
+setGlobalValidationSettings({
+    t: (path, params) => i18n.global.t(path, params),
+})
+
+createApp(App)
+    .use(createVuetify())
+    .use(i18n)
+    .use(createUIKit({
+        toast: { timeout: 6000 },
+    }))
+    .mount('#app')
+```
+
+```vue
+<template>
+    <VApp>
+        <VMain>
+            <RouterView />
+        </VMain>
+        <UiKitOutlet />
+    </VApp>
+</template>
+
+<script lang="ts" setup>
+    import { UiKitOutlet } from '@schwarzdavid/ui-kit'
+</script>
+```
+
+The composables must be called inside `setup()` or inside `app.runWithContext()`. Anywhere else they throw `@schwarzdavid/ui-kit is not available in this context. Install it with app.use(createUIKit()) and call its composables inside setup() or app.runWithContext().`
+
+## Usage
+
+### useDialog
+
+```ts
+import { useDialog } from '@schwarzdavid/ui-kit'
+
+const dialog = useDialog()
+
+const confirmed = await dialog.confirm('items.delete.title', 'items.delete.content')
+await dialog.info('about.title', 'about.content')
+```
+
+`useDialog()` also provides `confirm()` and `form()`, which renders your own input or form component and resolves with its value.
+
+### useToast
+
+```ts
+import { useToast } from '@schwarzdavid/ui-kit'
+
+const toast = useToast()
+
+await toast.success('items.saved')
+toast.error('Upload failed', { translateMessage: false, timeout: 8000 })
+```
+
+Each toast function returns a Promise that resolves when the toast disappears.
+
+### useLoading
+
+```ts
+import { useLoading } from '@schwarzdavid/ui-kit'
+
+const { loading, action: save } = useLoading(async (id: number) => api.save(id), { overlay: true })
+
+const result = await save(42)
+```
+
+### Validators
+
+The validators entry wraps the `@vuelidate/validators` rules so that their messages are translated. Call `setGlobalValidationSettings` once with your translation function (see Setup), then use the rules with `useVuelidate`. `useVuelidateErrors` turns a validation object into a nested object of translated error messages.
+
+```ts
+import useVuelidate from '@vuelidate/core'
+import { email, minLength, required, useVuelidateErrors } from '@schwarzdavid/ui-kit/validators'
+
+const v = useVuelidate({
+    name: { required, minLength: minLength(3) },
+    email: { required, email },
+}, state)
+
+const errors = useVuelidateErrors(v)
+```
+
+## Documentation
+
+The full documentation, including live demos of every composable, is a Storybook. Run it locally with:
+
+```sh
+npm run docs
+```
+
+and open http://localhost:6006.
+
+## Development
+
+| Script               | Description                                                    |
+|----------------------|----------------------------------------------------------------|
+| `npm run lint`       | Run ESLint                                                     |
+| `npm run check`      | Type-check the project with `vue-tsc`                          |
+| `npm test`           | Run the Vitest test suite                                      |
+| `npm run build:lib`  | Type-check and build the library into `dist/`                  |
+| `npm run build:docs` | Build the static Storybook into `storybook-static/`            |
+
+## Known limitations
+
+- `useVuelidateErrors` has not been made to work with `$each` collection validators (rules built with Vuelidate's `helpers.forEach`). Errors of the individual collection items are not mapped into the result; read them from the validation object directly.
+
+## License
+
+Apache-2.0

package/dist/main.d.ts

@@ -1,19 +1,121 @@
+import { AllowedComponentProps } from 'vue';
 import { Component } from 'vue';
+import { ComponentCustomProps } from 'vue';
 import { ComponentOptionsMixin } from 'vue';
 import { ComponentProps } from 'vue-component-type-helpers';
 import { ComponentProvideOptions } from 'vue';
-import { ComponentPublicInstance } from 'vue';
-import { ComputedOptions } from 'vue';
 import { DefineComponent } from 'vue';
-import { EmitFn } from 'vue';
 import { FunctionPlugin } from 'vue';
-import { IfEmptyObject } from 'type-fest';
+import { HasRequiredKeys } from 'type-fest';
 import { MaybeRefOrGetter } from 'vue';
-import { MethodOptions } from 'vue';
 import { PartialDeep } from 'type-fest';
 import { Promisable } from 'type-fest';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
+import { VNodeProps } from 'vue';
+
+declare const __VLS_base: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    close: () => any;
+    submit: () => any;
+    "update:modelValue": (value: boolean) => any;
+    "update:stage": (stage: SheetStage) => any;
+    opened: () => any;
+    closed: () => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onSubmit?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
+    "onUpdate:stage"?: ((stage: SheetStage) => any) | undefined;
+    onOpened?: (() => any) | undefined;
+    onClosed?: (() => any) | undefined;
+}>, {
+    form: boolean;
+    title: string;
+    persistent: boolean;
+    stage: SheetStage;
+    translateTitle: boolean;
+    expandable: boolean;
+    closable: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_base_2: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+    close: () => any;
+    submit: () => any;
+    "update:modelValue": (value: boolean) => any;
+    "update:stage": (stage: SheetStage) => any;
+    opened: () => any;
+    closed: () => any;
+}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onSubmit?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
+    "onUpdate:stage"?: ((stage: SheetStage) => any) | undefined;
+    onOpened?: (() => any) | undefined;
+    onClosed?: (() => any) | undefined;
+}>, {
+    width: DialogWidth;
+    form: boolean;
+    persistent: boolean;
+    stage: SheetStage;
+    translateTitle: boolean;
+    expandable: boolean;
+    closable: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare const __VLS_export: DefineComponent<{}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+
+declare const __VLS_export_2: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+
+declare const __VLS_export_3: __VLS_WithSlots_2<typeof __VLS_base_2, __VLS_Slots_2>;
+
+declare type __VLS_Props = {
+    modelValue: boolean;
+    stage?: SheetStage;
+    title?: string;
+    translateTitle?: boolean;
+    expandable?: boolean;
+    closable?: boolean;
+    persistent?: boolean;
+    form?: boolean;
+};
+
+declare type __VLS_Props_2 = {
+    modelValue: boolean;
+    title: string;
+    translateTitle?: boolean;
+    width?: DialogWidth;
+    closable?: boolean;
+    persistent?: boolean;
+    form?: boolean;
+    expandable?: boolean;
+    stage?: SheetStage;
+};
+
+declare type __VLS_Slots = {
+    default?: () => unknown;
+    preview?: () => unknown;
+    header?: () => unknown;
+    actions?: () => unknown;
+};
+
+declare type __VLS_Slots_2 = {
+    default?: () => unknown;
+    preview?: () => unknown;
+    header?: () => unknown;
+    actions?: () => unknown;
+};
+
+declare type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+declare type __VLS_WithSlots_2<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
 
 declare interface ConfirmDialogBaseProps {
     title: string;
@@ -22,7 +124,7 @@ declare interface ConfirmDialogBaseProps {
     rejectCta?: Partial<DialogCta>;
     throwOnReject?: boolean;
     permanent?: boolean;
-    maxWidth?: number | string;
+    width?: DialogWidth;
     highlightCta?: 'confirm' | 'reject' | false;
     level?: ConfirmDialogLevel;
 }
@@ -44,64 +146,95 @@ export declare interface ConfirmDialogTextContent extends ConfirmDialogBaseProps
     translateContent?: boolean;
 }
 
-export declare function createUIKit(options?: PartialDeep<PluginOptions>): FunctionPlugin<void>;
+declare interface CreateToastQueueEntry {
+    type: ToastType;
+    message: string;
+    translateMessage: boolean;
+    timeout: number | false;
+    action?: ToastAction;
+    resolve(triggered: boolean): void;
+}
+
+export declare function createUIKit(options?: CreateUIKitOptions): FunctionPlugin<unknown[]>;
+
+export declare type CreateUIKitOptions = PartialDeep<Omit<PluginOptions, 'components'>> & {
+    components?: {
+        dialog?: Partial<PluginDialogComponentOptions>;
+        toast?: Component;
+    };
+};
 
-declare interface DialogActionCta extends DialogCta {
+export declare interface DialogActionCta extends DialogCta {
     action(): unknown;
 }
 
 export declare interface DialogComposable {
     info(title: string, content: string): Promise<null>;
     info<T = void, C extends Component = Component>(options: InfoDialogProps<T, C>): Promise<T extends void ? null : (T | null)>;
-    prompt<T, R extends boolean = false, C extends PromptDialogComponent<T> = PromptDialogComponent<T>>(options: PromptDialogProps<T, R, C>): Promise<R extends true ? T : T | null>;
     confirm(title: string, content: string, level?: ConfirmDialogLevel): Promise<boolean>;
     confirm<C extends Component = Component>(options: ConfirmDialogProps<C>): Promise<boolean>;
-    form<R, T = R, RejectOnEmpty extends boolean = false>(options: FormDialogProps<R, T, RejectOnEmpty>): Promise<RejectOnEmpty extends true ? R : R | null>;
+    form<T, R = T, Required extends boolean = false, C extends Component = Component>(options: FormDialogProps<T, R, Required, C>): Promise<Required extends true ? R : R | null>;
 }
 
-declare interface DialogCta {
+export declare interface DialogCta {
     text: string;
     translateText: boolean;
 }
 
-declare type DialogProps<T extends object> = IfEmptyObject<T, object, {
-    props: T;
-}>;
-
-declare interface DialogValueCta<T> extends DialogCta {
-    value: T;
+export declare interface DialogEntryContext<Data = unknown, Value = unknown> {
+    readonly id: string;
+    readonly data: Data;
+    resolve(value: Value): void;
+    reject(reason?: unknown): void;
 }
 
-export declare type FormDialogAction<T, R> = (value: T) => Promise<R>;
+export declare interface DialogFormContext {
+    submit(): Promise<void>;
+    loading: Readonly<Ref<boolean>>;
+}
 
-export declare type FormDialogComponent<T> = new () => Omit<ComponentPublicInstance, '$emit'> & FormDialogComponentExposed<T> & {
-    $emit: EmitFn<FormDialogComponentEmits>;
-};
+export declare type DialogFormFinish<T> = () => Promisable<T>;
 
-export declare type FormDialogComponentEmits = {
-    save: [];
+declare type DialogProps<T extends object> = PropsRequired<OwnProps<T>> extends true ? {
+    props: OwnProps<T>;
+} : {
+    props?: OwnProps<T>;
 };
 
-export declare interface FormDialogComponentExposed<T> {
-    finish(): Promisable<T>;
+export declare interface DialogValueCta<T> extends DialogCta {
+    value: T;
 }
 
-export declare type FormDialogProps<R, T = R, RejectOnEmpty extends boolean = false, C extends FormDialogComponent<T> = FormDialogComponent<T>, P extends object = ComponentProps<C>> = DialogProps<P> & {
+export declare type DialogWidth = 'sm' | 'md' | 'lg' | number;
+
+export declare type FormDialogAction<T, R> = (value: T) => Promise<R>;
+
+export declare interface FormDialogBaseProps<T, R = T, Required extends boolean = false, C extends Component = Component> {
     title: string;
-    translateTitle?: string;
+    translateTitle?: boolean;
+    width?: DialogWidth;
     saveCta?: Partial<DialogCta>;
     abortCta?: Partial<DialogCta>;
     component: C;
+    initialValue?: MaybeRefOrGetter<T>;
     action?: FormDialogAction<T, R>;
-    rejectOnEmpty?: RejectOnEmpty;
-};
+    required?: Required;
+}
+
+export declare type FormDialogInjectedProp = 'modelValue' | 'onUpdate:modelValue' | 'toolbar';
+
+declare type FormDialogModelCheck<T, C extends Component> = unknown extends T ? unknown : 'modelValue' extends keyof ComponentProps<C> ? [T] extends [NonNullable<ComponentProps<C>['modelValue']>] ? unknown : {
+    component: never;
+} : unknown;
+
+export declare type FormDialogProps<T, R = T, Required extends boolean = false, C extends Component = Component> = DialogProps<Omit<ComponentProps<C>, FormDialogInjectedProp>> & FormDialogModelCheck<T, C> & FormDialogBaseProps<T, R, Required, C>;
 
 declare interface InfoDialogBaseProps<T> {
     title: string;
     translateTitle?: boolean;
     additionalCta?: InteractiveDialogCta<T>[];
-    defaultCta?: Partial<InteractiveDialogCta<T>> | false;
-    width?: number | string;
+    defaultCta?: Partial<DialogCta> | false;
+    width?: DialogWidth;
 }
 
 export declare type InfoDialogComponentContent<T = void, C extends Component = Component> = DialogProps<ComponentProps<C>> & InfoDialogBaseProps<T> & {
@@ -115,81 +248,118 @@ export declare interface InfoDialogTextContent<T> extends InfoDialogBaseProps<T>
     translateContent?: boolean;
 }
 
-declare type InteractiveDialogCta<T> = DialogActionCta | DialogValueCta<T>;
+export declare type InteractiveDialogCta<T> = DialogActionCta | DialogValueCta<T>;
 
-export declare type LoadingAction = (...args: any) => any | Promise<any>;
+export declare type LoadingAction = (...args: never[]) => unknown;
 
 export declare interface LoadingComposable<A extends LoadingAction> {
     loading: Readonly<Ref<boolean>>;
     action(...args: Parameters<A>): Promise<Awaited<ReturnType<A>>>;
 }
 
-declare type PluginI18nMessageKey = 'save' | 'cancel' | 'close' | 'yes' | 'no';
+declare type OwnProps<T extends object> = Omit<T, keyof VNodeProps | keyof AllowedComponentProps | keyof ComponentCustomProps>;
+
+export declare interface PluginComponentOptions {
+    dialog: PluginDialogComponentOptions;
+    toast: Component;
+}
+
+export declare interface PluginDialogComponentOptions {
+    info: Component;
+    confirm: Component;
+    form: Component;
+}
+
+export declare interface PluginDialogOptions {
+    closeOnOverlayClick: boolean;
+}
 
-declare interface PluginI18nOptions {
+export declare type PluginI18nMessageKey = 'save' | 'cancel' | 'close' | 'yes' | 'no' | 'saveFailed' | 'unknownError' | 'expand' | 'collapse';
+
+export declare interface PluginI18nOptions {
     messages: Record<PluginI18nMessageKey, string>;
 }
 
-declare interface PluginLoadingOptions {
+export declare interface PluginLoadingOptions {
     delay: number | false;
     overlay: boolean;
 }
 
-declare interface PluginOptions {
+export declare interface PluginOptions {
     loading: PluginLoadingOptions;
     toast: PluginToastOptions;
+    dialog: PluginDialogOptions;
     i18n: PluginI18nOptions;
+    components: PluginComponentOptions;
 }
 
-declare interface PluginToastOptions {
+export declare interface PluginToastOptions {
     timeout: number;
+    errorTimeout: number | false;
 }
 
-export declare type PromptDialogComponent<T> = ComponentPublicInstance<PromptDialogComponentProps<T>, any, any, ComputedOptions, MethodOptions, ComponentOptionsMixin, ComponentOptionsMixin, PromptDialogComponentEmits<T>>;
+declare type PropsRequired<P extends object> = string extends keyof P ? false : HasRequiredKeys<P>;
 
-export declare type PromptDialogComponentEmits<T> = (name: 'update:modelValue', value: T | null) => unknown;
+export declare type SheetStage = 'preview' | 'content' | 'fullscreen';
 
-export declare interface PromptDialogComponentProps<T> {
-    modelValue: T | null;
-    toolbar: HTMLElement;
+export declare interface ToastAction {
+    text: string;
+    translateText?: boolean;
+    handler?: () => unknown;
 }
 
-export declare type PromptDialogProps<T, R extends boolean = false, C extends PromptDialogComponent<T> = PromptDialogComponent<T>> = DialogProps<Omit<ComponentProps<C>, keyof PromptDialogComponentProps<T>>> & {
-    title: string;
-    translateTitle?: boolean;
-    saveCta?: Partial<DialogCta>;
-    abortCta?: Partial<DialogCta>;
-    initialValue?: MaybeRefOrGetter<T>;
-    size?: PromptDialogSize;
-    required?: R;
-    component: C;
-};
-
-export declare enum PromptDialogSize {
-    SMALL = "sm",
-    LARGE = "lg"
+export declare interface ToastComposable {
+    info: ToastFunction;
+    warn: ToastFunction;
+    error: ToastFunction;
+    success: ToastFunction;
 }
 
-export declare interface ToastComposable {
-    info(message: string, options?: Partial<ToastOptions>): Promise<void>;
-    warn(message: string, options?: Partial<ToastOptions>): Promise<void>;
-    error(message: string, options?: Partial<ToastOptions>): Promise<void>;
-    success(message: string, options?: Partial<ToastOptions>): Promise<void>;
+export declare interface ToastEntryContext {
+    readonly entry: ToastEntryData;
+    close(): void;
+    trigger(): void;
 }
 
-declare interface ToastOptions {
-    timeout: number;
+export declare type ToastEntryData = Omit<ToastQueueEntry, 'resolve'>;
+
+export declare type ToastFunction = (message: string, options?: Partial<ToastOptions>) => Promise<boolean>;
+
+export declare interface ToastOptions {
+    timeout: number | false;
     translateMessage: boolean;
+    action?: ToastAction;
 }
 
-export declare const UiKitOutlet: DefineComponent<    {}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export declare interface ToastQueueEntry extends CreateToastQueueEntry {
+    id: string;
+}
+
+export declare enum ToastType {
+    SUCCESS = "success",
+    INFO = "info",
+    WARNING = "warning",
+    ERROR = "error"
+}
+
+export declare const UiBottomSheet: typeof __VLS_export_2;
+
+export declare const UiKitOutlet: typeof __VLS_export;
+
+export declare const UiResponsiveDialog: typeof __VLS_export_3;
 
 export declare function useDialog(): DialogComposable;
 
+export declare function useDialogEntry<Data, Value = unknown>(): DialogEntryContext<Data, Value>;
+
+export declare function useDialogForm<T>(finish: DialogFormFinish<T>): DialogFormContext;
+
 export declare function useLoading<A extends LoadingAction>(actionCallback: A, options?: Partial<PluginLoadingOptions>): LoadingComposable<A>;
 
 export declare function useLoadingOverlay(): Ref<boolean>;
 
 export declare function useToast(): ToastComposable;
 
+export declare function useToastEntry(): ToastEntryContext;
+
 export { }