@knitify/vue 1.0.0 → 2.1.0

package/README.md

@@ -1,86 +1,113 @@
-# @knitify/vue
-
-Vue 3 components for [Knitify](https://www.npmjs.com/package/@knitify/core), the core UI library
-powering the Knitware ecosystem. Each component wraps Knitify's markup, classes, and interactive
-behaviour behind a typed Vue API.
-
-## Installation
-
-```bash
-pnpm add @knitify/vue @knitify/core
-```
-
-`@knitify/core`, `vue`, and `vue-router` are peer dependencies — install them alongside this
-package.
-
-| Peer            | Range     |
-| --------------- | --------- |
-| `@knitify/core` | `^1.1.0`  |
-| `vue`           | `^3.5.12` |
-| `vue-router`    | `^4.0.3`  |
-
-## Setup
-
-The components ship unstyled on their own — Knitify's stylesheet lives in `@knitify/core` and must
-be imported once by the consuming app:
-
-```ts
-import '@knitify/core/main.css'
-```
-
-### Register every component
-
-The default export is a Vue plugin that registers all components globally:
-
-```ts
-import { createApp } from 'vue'
-import Knitify from '@knitify/vue'
-import '@knitify/core/main.css'
-import App from './App.vue'
-
-createApp(App).use(Knitify).mount('#app')
-```
-
-### Or import individually
-
-Every component is also a named export, which keeps your bundle to what you actually use:
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { KButton, KModal } from '@knitify/vue'
-
-const modal = ref<InstanceType<typeof KModal>>()
-</script>
-
-<template>
-  <KButton variant="info" @click="modal?.show()">Open</KButton>
-  <KModal ref="modal" title="Hello" closable>Content</KModal>
-</template>
-```
-
-`KModal` is opened through the instance it exposes (`show`, `hide`, `toggle`) rather than a
-`v-model`, which keeps it in step with core's own `data-kt-modal-toggle` attribute.
-
-Colour-carrying props take Knitify's semantic intents — `caution`, `warning`, `critical`, `info`,
-`discovery`, `affirm` — rather than generic names like `primary`.
-
-## What's included
-
-47 components covering layout (`KContainer`, `KGrid`, `KWorkspace`), navigation (`KNavbar`,
-`KBreadcrumb`, `KTabs`, `KMenuList`), forms (`KInput`, `KSelect`, `KCheckbox`, `KRadio`,
-`KToggle`, `KCalendar`), overlays (`KModal`, `KDrawer`, `KPopover`, `KTooltip`, `KDropdown`),
-feedback (`KAlert`, `KProgress`, `KNotificationList`), and data display (`KTable`,
-`KCard`, `KAvatar`, `KBadge`, `KAccordion`, `KCollapse`, `KFileTree`, `KChat`).
-
-Alongside the components:
-
-- `useToast()` — composable for pushing toasts imperatively
-- `accordionGroupKey`, `chatBusyKey` — injection keys for building on the accordion and chat
-  primitives
-- Prop and emit types for every component, re-exported from the package root
-
-## TypeScript
-
-The package is TypeScript-first and ships declarations at `dist/types/index.d.ts`. No
-`@types/*` package is needed.
+# @knitify/vue
+
+Vue 3 components for [Knitify](https://www.npmjs.com/package/@knitify/core), the core UI library
+powering the Knitware ecosystem. Each component wraps Knitify's markup, classes, and interactive
+behaviour behind a typed Vue API.
+
+## Installation
+
+```bash
+pnpm add @knitify/vue @knitify/core
+```
+
+`@knitify/core`, `vue`, and `vue-router` are peer dependencies — install them alongside this
+package.
+
+| Peer            | Range     |
+| --------------- | --------- |
+| `@knitify/core` | `^1.1.0`  |
+| `vue`           | `^3.5.12` |
+| `vue-router`    | `^4.0.3`  |
+
+## Setup
+
+The components ship unstyled on their own — Knitify's stylesheet lives in `@knitify/core` and must
+be imported once by the consuming app:
+
+```ts
+import '@knitify/core/main.css'
+```
+
+### Register every component
+
+The default export is a Vue plugin that registers all components globally:
+
+```ts
+import { createApp } from 'vue'
+import Knitify from '@knitify/vue'
+import '@knitify/core/main.css'
+import App from './App.vue'
+
+createApp(App).use(Knitify).mount('#app')
+```
+
+### Or import individually
+
+Every component is also a named export, which keeps your bundle to what you actually use:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { KButton, KModal } from '@knitify/vue'
+
+const modal = ref<InstanceType<typeof KModal>>()
+</script>
+
+<template>
+  <KButton variant="info" @click="modal?.show()">Open</KButton>
+  <KModal ref="modal" title="Hello" closable>Content</KModal>
+</template>
+```
+
+`KModal` is opened through the instance it exposes (`show`, `hide`, `toggle`) rather than a
+`v-model`, which keeps it in step with core's own `data-kt-modal-toggle` attribute.
+
+Colour-carrying props take Knitify's semantic intents — `caution`, `warning`, `critical`, `info`,
+`discovery`, `affirm` — rather than generic names like `primary`.
+
+## What's included
+
+47 components covering layout (`KContainer`, `KGrid`, `KWorkspace`), navigation (`KNavbar`,
+`KBreadcrumb`, `KTabs`, `KMenuList`), forms (`KInput`, `KSelect`, `KCheckbox`, `KRadio`,
+`KToggle`, `KCalendar`), overlays (`KModal`, `KDrawer`, `KPopover`, `KTooltip`, `KDropdown`),
+feedback (`KAlert`, `KProgress`, `KNotificationList`), and data display (`KTable`,
+`KCard`, `KAvatar`, `KBadge`, `KAccordion`, `KCollapse`, `KFileTree`, `KChat`).
+
+Alongside the components:
+
+- `useToast()` — composable for pushing toasts imperatively
+- `v-tooltip` — directive form of `KTooltip` (`v-tooltip:bottom="'Save'"`), registered by the
+  plugin and exported as `vTooltip` for local use
+- `accordionGroupKey`, `chatBusyKey` — injection keys for building on the accordion and chat
+  primitives
+- Prop and emit types for every component, re-exported from the package root
+
+### Chat dock with a backend
+
+`KMessenger` wires the chat dock to your API with loader functions; `useChatDock` is the same state without the rendering.
+
+```vue
+<script setup lang="ts">
+import type { ChatDockLoaders } from '@knitify/vue'
+
+const loaders: ChatDockLoaders = {
+  loadConversations: () => api.conversations(),
+  loadMessages: (id, cursor) => api.messages(id, cursor),
+  sendMessage: (id, text) => api.send(id, text),
+}
+</script>
+
+<template>
+  <KMessenger :loaders="loaders" />
+</template>
+```
+
+The loaders are read once, when the component mounts — so bind a stable object
+rather than an inline literal, which a re-render would replace to no effect.
+
+Note that Vue unwraps refs on an exposed object, so through a template ref `conversations`, `openIds` and `listLoading` read as plain values rather than refs; the store you create yourself with `useChatDock` keeps them as refs.
+
+## TypeScript
+
+The package is TypeScript-first and ships declarations at `dist/types/index.d.ts`. No
+`@types/*` package is needed.