vue-composable-ui 0.0.1

package/.github/workflows/deploy.yml

@@ -0,0 +1,21 @@
+name: Publish Package to npmjs
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Deploy Docs to Pages
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
+      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm # or pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm ci # or pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "Vue.volar",
+    "Vue.vscode-typescript-vue-plugin",
+    "puppet.puppet-vscode"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 dzapletin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Vue Composable UI (WIP)
+
+Docs - https://dzapletin.github.io/vue-composable-ui/

package/docs/.vitepress/config.mts

@@ -0,0 +1,40 @@
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Vue Composable UI",
+  description: "A truly headless UI framework",
+  base: "/vue-composable-ui/",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [{ text: "Home", link: "/" }],
+
+    sidebar: [
+      {
+        text: "Composables",
+        items: [
+          { text: "useList", link: "/composables/list" },
+          { text: "useListOption", link: "/composables/list-option" },
+          { text: "usePopover", link: "/composables/popover" },
+          { text: "useFormControl", link: "/composables/form-control" },
+        ],
+      },
+      {
+        text: "Components",
+        items: [
+          { text: "Listbox", link: "/components/listbox" },
+          { text: "Tabs", link: "/components/tabs" },
+          { text: "Popover", link: "/components/popover" },
+          { text: "Tooltip", link: "/components/tooltip" },
+          { text: "Menu", link: "/components/menu" },
+          { text: "Combobox", link: "/components/combobox" },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/dzapletin/vue-composable-ui" },
+    ],
+  },
+  lastUpdated: true,
+});

package/docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./style.scss";
+
+export default DefaultTheme;

package/docs/.vitepress/theme/style.scss

@@ -0,0 +1,155 @@
+.d-demo {
+  display: flex;
+  gap: 1rem;
+  flex-wrap: wrap;
+  justify-content: center;
+  justify-items: stretch;
+  position: relative;
+  border-radius: 1rem;
+  padding: 5rem;
+  background: linear-gradient(90deg, #e3ffe7 0%, #d9e7ff 100%);
+  overflow: hidden;
+
+  &__column {
+    flex-grow: 1;
+  }
+
+  h5 {
+    font-weight: 600;
+    line-height: 24px;
+    font-size: 16px;
+    margin-bottom: 0.5rem;
+    color: black;
+  }
+}
+
+.d-demo [tabindex]:not([tabindex="-1"]):focus {
+  outline: 3px solid DeepPink;
+  outline-offset: 2px;
+}
+
+.d-pointer {
+  cursor: pointer;
+}
+
+.d-btn {
+  padding: 0.375rem 0.75rem;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+  line-height: 1.5;
+  border: 1px solid transparent;
+  background-color: #6267ec;
+  color: white;
+
+  &:hover {
+    background-color: #5047e0;
+  }
+}
+
+.d-tooltip {
+  background-color: rgba($color: #000, $alpha: 0.8);
+  color: white;
+  border-radius: 0.25rem;
+  padding: 0.25rem 0.5rem;
+  margin: 0.5rem 0;
+}
+
+.d-popover {
+  z-index: 20;
+  outline: none;
+  padding: 1rem;
+  background: white;
+  color: black;
+  border-radius: 0.5rem;
+  box-shadow: 0 14px 44px rgba(0, 0, 0, 0.12), 0 3px 9px rgba(0, 0, 0, 0.12);
+  margin: 0.5rem 0;
+
+  &--h {
+    margin: 0 0.5rem;
+  }
+}
+
+.d-menu {
+  @extend .d-popover;
+  padding: 0.25rem;
+  margin: 0.25rem 0;
+}
+
+.d-menu-item {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.25rem 0.5rem;
+  outline: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  user-select: none;
+  &[aria-disabled="true"] {
+    color: gray;
+    cursor: default;
+  }
+  &[data-active="true"] {
+    background-color: #6267ec;
+    color: white;
+  }
+}
+
+.d-input {
+  padding: 0.375rem 0.75rem;
+  border-radius: 0.25rem;
+  background: white;
+  border: 1px solid #d1d5da;
+  outline: none;
+  width: 100%;
+  max-width: 100%;
+  color: black;
+  &:focus {
+    border-color: #6267ec;
+  }
+
+  &--select {
+    cursor: pointer;
+    position: relative;
+    &::after {
+      content: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxZW0iIGhlaWdodD0iMWVtIiB2aWV3Qm94PSIwIDAgMjQgMjQiPjxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0iY3VycmVudENvbG9yIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS13aWR0aD0iMS41IiBkPSJNOC4yNSAxNUwxMiAxOC43NUwxNS43NSAxNW0tNy41LTZMMTIgNS4yNUwxNS43NSA5Ii8+PC9zdmc+");
+      position: absolute;
+      right: 0;
+      top: 0;
+    }
+  }
+}
+
+.d-combobox {
+  @extend .d-input;
+  padding: 0.25rem;
+  display: flex;
+  gap: 0.25rem;
+
+  &__tags {
+    display: flex;
+    gap: 0.25rem;
+    align-items: center;
+    color: gray;
+  }
+
+  input {
+    flex-grow: 1;
+    width: 100%;
+    padding: 0.125rem 0.5rem;
+  }
+}
+
+.d-tag {
+  background-color: #6267ec;
+  color: white;
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.5rem;
+  white-space: nowrap;
+}
+
+.d-no-options {
+  padding: 0.25rem 0.5rem;
+  text-align: center;
+  color: gray;
+}

package/docs/components/combobox.md

@@ -0,0 +1,174 @@
+<script setup>
+import ComboboxDemo from './demos/combobox.vue'
+import ComboboxTagsDemo from './demos/combobox_tags.vue'
+</script>
+
+# Combobox Components
+
+A combobox is a composite widget that combines an input field with a popup providing possible values for that input field.
+
+Based on:
+
+- [usePopover](/composables/popover)
+- [useList](/composables/list)
+- [useListOption](/composables/list-option)
+- [useFormControl](/composables/form-control)
+
+## Demo
+
+<ComboboxDemo />
+::: details Code
+<<< ./demos/combobox.vue
+:::
+
+## Complex Widget Example
+
+Autocomplete + tags
+
+<ComboboxTagsDemo />
+::: details Code
+<<< ./demos/combobox_tags.vue
+:::
+
+## Combobox
+
+The root component.
+
+### Properties
+
+| Property         | Required | Description                                                                                                    | Type                                                  | Default                                                                                                                                     |
+| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **modelValue**   | true     | The selected value. Set to an array to enable multiselection.                                                  | `any` \| `any[]`                                      | `undefined`                                                                                                                                 |
+| **displayValue** | false    | A function that takes the combobox value and returns a string representation that is shown in the input.       | `(value: unknown \| unknown[]) => string`             | Calls `.toString()` on the provided value. For multi-selectable combobox converts every value to string and joins the results with a comma. |
+| **name**         | false    | The name of the field that is submitted when using inside a form.                                              | `string`                                              | `undefined`                                                                                                                                 |
+| **formValue**    | false    | A function that takes a selected item value and transforms it into a value to submit when using inside a form. | `(item: unknown) => Record<string, string> \| string` | Returns the value unchanged                                                                                                                 |
+| **id**           | false    | The ID of the combobox input.                                                                                  | `string`                                              | Auto-generated                                                                                                                              |
+| **activatorId**  | false    | The ID of the activator element.                                                                               | `string`                                              | Equals to the `id`                                                                                                                          |
+
+### Slots
+
+#### input
+
+The `input` slot is used to provide an input element and possibly an activator. The slot passes the following properties:
+
+| Property      | Description                                               | Type           |
+| ------------- | --------------------------------------------------------- | -------------- |
+| **attrs**     | Required attributes that **must** be binded to the input. | `object`       |
+| **isOpen**    | The status of the popover.                                | `Ref<boolean>` |
+| **toggle**    | Toggle the popover.                                       | `() => void`   |
+| **popoverId** | The ID of the popover dialog.                             | `string`       |
+
+In a complex component you may need to wrap the input in a container element which must serve as an activator for the popover. You can achieve this by setting the `activatorId` property and assigning it to the wrapper element in the input slot.
+
+```vue
+<Combobox activatorId="activator">
+  <template #input="{ popoverId, attrs, toggle, isOpen }">
+    <div id="activator">
+      <input
+        v-bind="attrs"
+      />
+      <button
+        @click="toggle"
+        :aria-controls="isOpen ? popoverId : undefined"
+        :aria-expanded="isOpen"
+        aria-haspopup="listbox"
+        tabindex="-1"
+      >
+        Toggle
+      </button>
+    </div>
+  </template>
+</Combobox>
+```
+
+### Keyboard interactions
+
+When closed:
+
+- `Space` / `Enter` - Opens the listbox.
+- `Down Arrow` / `Home` - Opens the listbox and moves focus to the first item.
+- `Up Arrow` / `End` - Opens the listbox and moves focus to the last item.
+
+When open:
+
+- `Space` - Selects the currently active item and closes the combobox (if it is not multiselectable).
+- `Enter` - Selects the currently active item and closes the combobox.
+- `Tab` - Selects the currently active item, closes the combobox and proceeds to the default tab action.
+- `Down Arrow` - Moves focus to the next item.
+- `Up Arrow` - Moves focus to the previous item.
+- `Home` - Moves focus to the first item.
+- `End` - Moves focus to the last item.
+- `Escape` - Closes the listbox.
+
+## ComboboxOptions
+
+Wraps a collection of options, has no properties.
+
+### ARIA roles and attributes
+
+Options container has the [listbox](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) role.
+
+## ComboboxOption
+
+### Properties
+
+| Property     | Required | Description                   | Type      | Default        |
+| ------------ | -------- | ----------------------------- | --------- | -------------- |
+| **value**    | true     | Value assigned to the item.   | `any`     |                |
+| **disabled** | false    | Whether the item is disabled. | `boolean` | `false`        |
+| **id**       | false    | The ID of the item.           | `string`  | Auto-generated |
+
+### Slots
+
+#### default
+
+| Attribute      | Description                           | Type      |
+| -------------- | ------------------------------------- | --------- |
+| **isSelected** | Whether the item is selected.         | `boolean` |
+| **isActive**   | Whether the item is active (focused). | `boolean` |
+
+### ARIA roles and attributes
+
+Options have the [option](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) role.
+
+The following attributes are automatically managed:
+
+- [aria-selected](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected)
+- [aria-disabled](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled)
+
+## Using in a Form
+
+When using Combobox in a form set the `name` attribute on the root component.
+
+If multiple items are selected, the values will be submitted as an array:
+
+```
+name[0]=value1&name[1]=value2...&name[n]=valueN
+```
+
+If a value is an object each of its properties will be submitted as a separate field:
+
+```js
+const value = {
+  login: "johny1223",
+  email: "johny@gmail.com",
+  isAdmin: false,
+};
+
+// Will be submitted as
+// name[login]=johny1223&name[email]=johny@gmail.com&name[isAdmin]=false
+```
+
+Sometimes you may want to transform a value before submitting the form. Use the `formValue` attribute to provide a transformer function, if multiple items are selected the function will be call for each value:
+
+```js
+const value = {
+  login: "johny1223",
+  email: "johny@gmail.com",
+  isAdmin: false,
+};
+const formValue = (value) => value.login;
+
+// Will be submitted as
+// name=johny@gmail.com
+```

package/docs/components/demos/combobox.vue

@@ -0,0 +1,142 @@
+<template>
+  <div class="d-demo">
+    <div class="d-demo__column">
+      <h5>Select-Only Combobox</h5>
+      <Combobox
+        v-model="fruit"
+        readonly
+        placeholder="Choose a fruit..."
+        class="d-input d-input--select"
+      >
+        <template #input="{ attrs }">
+          <button v-bind="attrs">ad</button>
+        </template>
+        <ComboboxOptions class="d-menu">
+          <ComboboxOption
+            v-for="opt in fruits"
+            :value="opt"
+            v-slot="{ isSelected }"
+            class="d-menu-item"
+          >
+            {{ opt }}
+            <svg
+              v-if="isSelected"
+              xmlns="http://www.w3.org/2000/svg"
+              width="1rem"
+              height="1rem"
+              viewBox="0 0 256 256"
+            >
+              <path
+                fill="currentColor"
+                d="m232.49 80.49l-128 128a12 12 0 0 1-17 0l-56-56a12 12 0 1 1 17-17L96 183L215.51 63.51a12 12 0 0 1 17 17Z"
+              />
+            </svg>
+          </ComboboxOption>
+        </ComboboxOptions>
+      </Combobox>
+    </div>
+
+    <div class="d-demo__column">
+      <h5>Select-Only Combobox</h5>
+      <Combobox
+        v-model="fruit"
+        readonly
+        placeholder="Choose a fruit..."
+        class="d-input d-input--select"
+      >
+        <ComboboxOptions class="d-menu">
+          <ComboboxOption
+            v-for="opt in fruits"
+            :value="opt"
+            v-slot="{ isSelected }"
+            class="d-menu-item"
+          >
+            {{ opt }}
+            <svg
+              v-if="isSelected"
+              xmlns="http://www.w3.org/2000/svg"
+              width="1rem"
+              height="1rem"
+              viewBox="0 0 256 256"
+            >
+              <path
+                fill="currentColor"
+                d="m232.49 80.49l-128 128a12 12 0 0 1-17 0l-56-56a12 12 0 1 1 17-17L96 183L215.51 63.51a12 12 0 0 1 17 17Z"
+              />
+            </svg>
+          </ComboboxOption>
+        </ComboboxOptions>
+      </Combobox>
+    </div>
+
+    <div class="d-demo__column">
+      <h5>Multiselectable Combobox</h5>
+      <Combobox
+        v-model="value"
+        :displayValue="(items: any[]) => items.map((i) => i.name).join(', ')"
+        readonly
+        placeholder="Select some people..."
+        class="d-input d-input--select"
+      >
+        <ComboboxOptions class="d-menu">
+          <ComboboxOption
+            v-for="opt in options"
+            :value="opt"
+            v-slot="{ isSelected }"
+            class="d-menu-item"
+          >
+            {{ opt.name }}
+            <svg
+              v-if="isSelected"
+              xmlns="http://www.w3.org/2000/svg"
+              width="1rem"
+              height="1rem"
+              viewBox="0 0 256 256"
+            >
+              <path
+                fill="currentColor"
+                d="m232.49 80.49l-128 128a12 12 0 0 1-17 0l-56-56a12 12 0 1 1 17-17L96 183L215.51 63.51a12 12 0 0 1 17 17Z"
+              />
+            </svg>
+          </ComboboxOption>
+        </ComboboxOptions>
+      </Combobox>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { Combobox, ComboboxOptions, ComboboxOption } from "../../../src/main";
+
+const fruit = ref("");
+const fruits = ["Apple", "Banana", "Grape", "Orange"];
+
+const value = ref([]);
+const options = [
+  {
+    id: 0,
+    name: "John Doe",
+  },
+  {
+    id: 1,
+    name: "Cris Doe",
+  },
+  {
+    id: 2,
+    name: "Michael Doe",
+  },
+  {
+    id: 3,
+    name: "Kim Doe",
+  },
+  {
+    id: 4,
+    name: "Boris Doe",
+  },
+  {
+    id: 5,
+    name: "Angelina Doe",
+  },
+];
+</script>