@xplortech/apollo-vue 2.8.0

package/README.md

@@ -0,0 +1,133 @@
+# Apollo Vue
+
+Vue 3 bindings for the Apollo design system (`@xplortech/apollo-core` web components). Use this package in Vue apps for props, events, and `v-model` on form controls.
+
+## Installation
+
+Published as **`@xplortech/apollo-vue`** on the public npm registry (same scope as `@xplortech/apollo-core` and `@xplortech/apollo-react`).
+
+```bash
+npm install @xplortech/apollo-vue @xplortech/apollo-core
+```
+
+Peer dependencies: **Vue 3+** and **TypeScript 5+**.
+
+Import styles once in your app (path may vary with your bundler):
+
+```ts
+import '@xplortech/apollo-vue/css/apollo.css';
+```
+
+## Registering components
+
+### Option A — global plugin (registers custom elements)
+
+```ts
+import { createApp } from 'vue';
+import { ComponentLibrary } from '@xplortech/apollo-vue';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(ComponentLibrary);
+app.mount('#app');
+```
+
+### Option B — import only what you use
+
+```vue
+<script setup lang="ts">
+import { XplButton, XplInput } from '@xplortech/apollo-vue';
+</script>
+
+<template>
+  <XplButton variant="primary">Save</XplButton>
+  <XplInput v-model="email" label="Email" type="email" />
+</template>
+```
+
+Importing from `@xplortech/apollo-vue` loads the generated proxies, which call `defineCustomElements()` from `@xplortech/apollo-core/loader`.
+
+## `v-model` (form components)
+
+These wrappers map `v-model` to the correct property and update event:
+
+| Component     | `v-model` binds to | Update event (internal) |
+|---------------|--------------------|-------------------------|
+| `XplInput`    | `value`            | `valueChange`           |
+| `XplCheckbox` | `checked`          | `checkboxChange`        | *|
+| `XplRadio`    | `checked`          | `radioChange`           |
+| `XplToggle`   | `checked`          | `toggleChange`          |
+| `XplSelect`   | `selectedValues`   | `changeEvent`           |
+
+Example:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { XplInput, XplCheckbox, XplSelect } from '@xplortech/apollo-vue';
+
+const name = ref('');
+const agreed = ref(false);
+const selected = ref<string | string[]>([]);
+</script>
+
+<template>
+  <XplInput v-model="name" label="Name" />
+  <XplCheckbox v-model="agreed" label="I agree" />
+  <XplSelect
+    v-model="selected"
+    label="Choose"
+    :choices="[]"
+    placeholder="Select…"
+  />
+</template>
+```
+
+_* `XplCheckbox` `v-model` binds to `checked`. When no `value` prop is set, it emits a **boolean** (checked state). When `value` is also set, it emits the **string** `value` when checked. Type your ref accordingly._
+
+**`XplChoicelist`:** there is no `v-model` mapping yet; use `@choicelistChange` / `@choicelistValueChange` and props manually.
+
+**Specialized input types:** `<XplInput type="date" />`, `type="time"`, `type="phone"`, `type="color"`, and `type="file"` all work with `v-model`. Internally, `xpl-input` renders a sub-component (e.g. `xpl-input-date`) and forwards its events. Prefer `<XplInput type="date" v-model="val" />` over using `XplInputDate` directly.
+
+## Events and complex props
+
+Stencil `@Event()` names are exposed as Vue emits (e.g. `@valueChange`, `@checkboxChange`). Pass objects and arrays as props the same way as with other Vue components:
+
+```vue
+<script setup lang="ts">
+import { XplTable } from '@xplortech/apollo-vue';
+const rows = [[]];
+const cols = [];
+function onSelect() {}
+</script>
+
+<template>
+  <XplTable :data="rows" :columns="cols" @table-select="onSelect" />
+</template>
+```
+
+## Suppressing unknown-element warnings
+
+If your bundler warns about `xpl-*` tags as unknown custom elements, tell the Vue compiler to treat them as web components:
+
+```ts
+// vite.config.ts
+import vue from '@vitejs/plugin-vue';
+
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag.startsWith('xpl-'),
+        },
+      },
+    }),
+  ],
+};
+```
+
+## Further reading
+
+- [Apollo repo](https://github.com/xplor/apollo)
+- Core components and behavior: `@xplortech/apollo-core` / Storybook in this monorepo