@deck9/ui 0.17.0-next.1 → 0.17.0

package/README.md

@@ -1,24 +1,120 @@
-# ui
+# @deck9/ui
 
-## Project setup
+Vue 3 components for Deck9 apps such as [Input](https://github.com/deck9/input), styled with Tailwind CSS 3. Storybook is the component reference: run `npm run storybook` in this repo.
+
+## Install
+
+```sh
+npm install @deck9/ui
+pnpm add @deck9/ui
+yarn add @deck9/ui
+bun add @deck9/ui
 ```
-yarn install
+
+Vue 3.3 or newer is a peer dependency. Pre-releases are on the `next` tag: `npm install @deck9/ui@next`.
+
+The steps below use npm. With another package manager, swap `npm install` for `pnpm add`, `yarn add` or `bun add`.
+
+## Use it in an app
+
+### Tailwind
+
+The package ships no CSS: its components use Tailwind 3 classes, and the app's Tailwind build creates them. In a new app, set up Tailwind 3:
+
+```sh
+npm install -D tailwindcss@3 postcss autoprefixer @tailwindcss/forms
+npx tailwindcss init -p
 ```
 
-### Compiles and hot-reloads for development
+In `tailwind.config.js`, add the package's bundle to `content`, plus the `grey` color and the forms plugin the components use. `darkMode: "class"` keeps the components light until the app sets a `dark` class. Without it, they turn dark whenever the computer is in dark mode.
+
+```js
+import colors from "tailwindcss/colors";
+import forms from "@tailwindcss/forms";
+
+export default {
+  darkMode: "class",
+  content: [
+    "./index.html",
+    "./src/**/*.{vue,js,ts}",
+    "./node_modules/@deck9/ui/dist/src/ui.mjs",
+  ],
+  theme: {
+    extend: {
+      colors: { grey: colors.slate },
+    },
+  },
+  plugins: [forms],
+};
 ```
-yarn serve
+
+Put Tailwind's layers in the app's main CSS file (in a Vite app: `src/style.css`):
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
 ```
 
-### Compiles and minifies for production
+### Icons
+
+The components draw icons with Font Awesome 6 and register only the few they use themselves. The app registers every other icon. Install Font Awesome 6, so the app and the components share one copy:
+
+```sh
+npm install @fortawesome/fontawesome-svg-core@6 @fortawesome/free-solid-svg-icons@6
 ```
-yarn build
+
+Register the icons once before the app mounts, for example in `src/main.js`:
+
+```js
+import { library } from "@fortawesome/fontawesome-svg-core";
+import { faRocket } from "@fortawesome/free-solid-svg-icons";
+
+library.add(faRocket);
+```
+
+Brand icons work the same way with `@fortawesome/free-brands-svg-icons@6`.
+
+### A first component
+
+```vue
+<script setup>
+import { D9Button, D9Icon } from "@deck9/ui";
+</script>
+
+<template>
+  <D9Button label="Launch" icon="rocket" />
+  <D9Icon name="rocket" size="2x" />
+</template>
 ```
 
-### Lints and fixes files
+Icon names are Font Awesome's names in kebab-case, without `fa`: `faChevronDown` is `chevron-down`.
+
+## Develop
+
+The repo uses npm (`package-lock.json`) and the Node version in `.nvmrc`.
+
+```sh
+npm ci
+npm run storybook   # Storybook on http://localhost:6006
+npm test            # Vitest
+npm run lint        # ESLint
+npm run check       # type check
+npm run build       # builds dist/, the files npm publishes
 ```
-yarn lint
+
+## Release
+
+Run `release.sh` on main. It takes the same arguments as `npm version`:
+
+```sh
+./release.sh preminor --preid next   # 0.17.0 → 0.18.0-next.0
+./release.sh prerelease              # 0.18.0-next.0 → 0.18.0-next.1
+./release.sh minor                   # 0.18.0-next.1 → 0.18.0
+./release.sh patch                   # 0.18.0 → 0.18.1
+./release.sh major                   # 0.18.1 → 1.0.0
 ```
 
-### Customize configuration
-See [Configuration Reference](https://cli.vuejs.org/config/).
+It pulls main, builds, bumps the version, pushes the commit and tag, and creates a GitHub release. You need push rights on main and a logged-in `gh`. The GitHub release starts the publish workflow, which publishes to npm through trusted publishing, without an npm token.
+
+A version with a dash, like `0.18.0-next.1`, is a pre-release: it goes to the `next` tag. Every other version goes to `latest`, which is what `npm install @deck9/ui` installs.

package/dist/Button/Button.vue.d.ts

@@ -14,13 +14,17 @@ declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_T
     iconPosition: string;
     isLoading: boolean;
     isDisabled: boolean;
-}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<ButtonProps>, {
+}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    click: (...args: any[]) => void;
+}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<ButtonProps>, {
     size: string;
     color: string;
     iconPosition: string;
     isLoading: boolean;
     isDisabled: boolean;
-}>>>, {
+}>>> & {
+    onClick?: ((...args: any[]) => any) | undefined;
+}, {
     size: Size;
     color: ColorScheme;
     isLoading: boolean;

package/dist/Menu/MenuContainer.vue.d.ts

@@ -1,16 +1,21 @@
 declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
     position: "right" | "left";
     usePortal: string | boolean;
+    label?: string | undefined;
 }>, {
     position: string;
     usePortal: boolean;
+    label: string;
 }>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
     position: "right" | "left";
     usePortal: string | boolean;
+    label?: string | undefined;
 }>, {
     position: string;
     usePortal: boolean;
+    label: string;
 }>>>, {
+    label: string;
     position: "right" | "left";
     usePortal: string | boolean;
 }, {}>, {

package/dist/Select/Select.vue.d.ts

@@ -1,20 +1,21 @@
 import { Size } from "../types/types";
 interface SelectOption {
     [key: string]: unknown;
-    id: string | number;
+    id?: string | number;
     label: string | number;
     icon?: string;
     disabled?: boolean;
 }
-declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
+declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
     id?: string | undefined;
     modelValue?: SelectOption | null | undefined;
     size?: Size | undefined;
     icon?: string | undefined;
     placeholder?: string | undefined;
     isDisabled?: boolean | undefined;
-    options: Array<SelectOption>;
+    options: SelectOption[];
     disabledBadge?: string | undefined;
+    by?: string | ((a: SelectOption | null, b: SelectOption) => boolean) | undefined;
 }>, {
     size: string;
     isDisabled: boolean;
@@ -27,8 +28,9 @@ declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_T
     icon?: string | undefined;
     placeholder?: string | undefined;
     isDisabled?: boolean | undefined;
-    options: Array<SelectOption>;
+    options: SelectOption[];
     disabledBadge?: string | undefined;
+    by?: string | ((a: SelectOption | null, b: SelectOption) => boolean) | undefined;
 }>, {
     size: string;
     isDisabled: boolean;
@@ -37,7 +39,13 @@ declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_T
 }, {
     size: Size;
     isDisabled: boolean;
-}, {}>;
+}, {}>, {
+    option?(_: {
+        option: SelectOption;
+        active: any;
+        selected: any;
+    }): any;
+}>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
 type __VLS_TypePropsToRuntimeProps<T> = {
@@ -56,3 +64,8 @@ type __VLS_WithDefaults<P, D> = {
 type __VLS_Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/Spinner/Spinner.vue.d.ts

@@ -1,2 +1,29 @@
-declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{}>>, {}, {}>;
+declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
+    label?: string | undefined;
+}>, {
+    label: string;
+}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
+    label?: string | undefined;
+}>, {
+    label: string;
+}>>>, {
+    label: string;
+}, {}>;
 export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};