vue-composable-ui 0.0.1 → 1.0.2

package/docs/composables/list.md

@@ -1,192 +0,0 @@
-# useList
-
-The composable implements single/multi-selection and navigation functionality for a list of HTML elements. It can be used to power a wide range of components: tabs, button groups, radio groups, comboboxes and all kinds of components where user has to select one or more values from a list.
-
-`useList` is meant to be used in conjunction with the [`useListOption`](/composables/list-option) composable.
-
-## Basic Usage
-
-::: code-group
-
-```vue [example.vue]
-<script setup>
-import { ref } from 'vue'
-
-const value = ref()
-</script>
-
-<template>
-  Selected value: {{value}}
-  <List v-model="value">
-    <Item value="1">Item 1</Item>
-    <Item value="2">Item 2</Item>
-    <Item value="3" :disabled="true">Item 3</Item>
-  <List>
-</template>
-```
-
-```vue [list.vue]
-<script setup>
-import { useList } from "vue-composable-ui";
-
-const model = defineModel();
-const list = useList(model);
-</script>
-
-<template>
-  <div>
-    <slot />
-  </div>
-</template>
-```
-
-```vue [item.vue]
-<script setup>
-import { useListOption } from "vue-composable-ui";
-import { ref } from "vue";
-
-const props = defineProps<{
-  value: any;
-  disabled?: boolean;
-}>()
-
-const itemEl = ref<HTMLElement>()
-const option = useListOption(itemEl, props.value, props.disabled);
-
-const onClick = () => option.select();
-</script>
-
-<template>
-  <div ref="itemEl" @click="onClick">
-    <slot />
-  </div>
-</template>
-```
-
-:::
-
-## Type Declarations
-
-### Composable
-
-```ts
-/**
- * Creates a reactive list of HTML elements with assigned values.
- *
- * @param value A ref to store the list value. Set to an array to enable multiselection.
- */
-export declare function useList(value: Ref<unknown>): UseListReturn;
-```
-
-### Return Type
-
-```ts
-export type ItemValue = unknown;
-export interface Item {
-  id: number;
-  element: Ref<HTMLElement | undefined>;
-  value: ItemValue;
-  disabled: MaybeRef<boolean>;
-}
-
-interface ActivationOptions {
-  /**
-   * Focus the corresponding HTML element
-   *
-   * @defaultValue false
-   */
-  focus?: boolean;
-}
-
-interface NavigationOptions {
-  /**
-   * Infinitely cycle throught the items
-   *
-   * @defaultValue false
-   */
-  loop?: boolean;
-}
-
-export interface UseListReturn {
-  /**
-   * Array of items
-   */
-  items: Readonly<ShallowRef<Item[]>>;
-  /**
-   * Multiselection flag
-   */
-  isMultiselectable: Readonly<Ref<boolean>>;
-  /**
-   * Currently active item
-   */
-  activeItem: ComputedRef<Item | undefined>;
-  /**
-   * Select the currently active item
-   */
-  selectActiveItem: () => void;
-  /**
-   * Activate the currently selected item
-   */
-  activateSelectedItem: (options?: ActivationOptions) => void;
-  /**
-   * Activate the first item
-   */
-  activateFirstItem: (options?: ActivationOptions) => void;
-  /**
-   * Activate the last item
-   */
-  activateLastItem: (options?: ActivationOptions) => void;
-  /**
-   * Activate next item
-   */
-  activateNextItem: (options?: ActivationOptions & NavigationOptions) => void;
-  /**
-   * Activate previous item
-   */
-  activatePrevItem: (options?: ActivationOptions & NavigationOptions) => void;
-}
-```
-
-### Injection Key
-
-> [!NOTE]
-> List items get unique ids that are not equal to their indexes in the `items` array returned by the composable. You need to access `item.id` to get its id value.
-
-```ts
-interface UseListInjectionKey {
-  /**
-   * The list value
-   */
-  value: Readonly<Ref<unknown>>;
-  /**
-   * Select an item by ID
-   */
-  selectItem: (itemId: number) => void;
-  /**
-   * Activate an item by ID
-   */
-  activateItem: (itemId: number, options?: ActivationOptions) => void;
-  /**
-   * Check if an item is selected
-   */
-  isSelected: (itemId: number) => boolean;
-  /**
-   * Check if an item is active
-   */
-  isActive: (itemId: number) => boolean;
-  /**
-   * Add an item to the list
-   *
-   * @returns New item ID
-   */
-  addItem: (
-    itemEl: HTMLElementType,
-    itemVal: ItemValue,
-    disabled?: MaybeRef<boolean>
-  ) => number;
-  /**
-   * Remove an item from the list by ID
-   */
-  removeItem: (itemId: number) => void;
-}
-```

package/docs/composables/popover.md

@@ -1,90 +0,0 @@
-# usePopover
-
-Popover is a floating container that appears next to its activator element above the main document flow. It can be used as a basic component for dropdown menus, comboboxes, tooltips, and more.
-
-The composable abstracts the logic of positioning a popover relative to its activating element and captures clicks to automatically close the popover.
-
-No event listeners are attached to the activating element to give the user full control over the way the popover is triggered.
-
-## Type Declarations
-
-### Composable
-
-```ts
-interface UsePopoverOptions {
-  /**
-   * The direction of the popover dialog
-   *
-   * @defaultValue `"down"`
-   */
-  direction?: "up" | "down" | "left" | "right";
-  /**
-   * The alignment of the popover dialog
-   *
-   * @defaultValue `"left"`
-   */
-  align?: "top" | "bottom" | "left" | "right" | "center" | "stretch";
-  /**
-   * The CSS position of the popover dialog
-   *
-   * @defaultValue `"fixed"`
-   */
-  position?: "fixed" | "absolute";
-  /**
-   * Close the popover on a click outside of the dialog
-   *
-   * @defaultValue `true`
-   */
-  closeOnOutsideClick?: boolean;
-  /**
-   * Close the popover on a click inside of the dialog
-   *
-   * @defaultValue `false`
-   */
-  closeOnInsideClick?: boolean;
-}
-
-/**
- *
- * @param activatorEl A template ref or a CSS selector
- * @param popupEl A template ref or a CSS selector
- * @param options Popover options
- */
-export declare function usePopover(
-  activatorEl: TemplateRefOrSelector,
-  popupEl: TemplateRefOrSelector,
-  options?: UsePopoverOptions
-): UsePopoverReturn;
-```
-
-### Return Type
-
-```ts
-interface FocusOptions {
-  /**
-   * Focus the popover/activator
-   *
-   * @defaultValue `true`
-   */
-  focus?: boolean;
-}
-
-export interface UsePopoverReturn {
-  /**
-   * The popover state
-   */
-  isOpen: Ref<boolean>;
-  /**
-   * Open the popover
-   */
-  open: (options?: FocusOptions) => void;
-  /**
-   * Close the popover
-   */
-  close: (options?: FocusOptions) => void;
-  /**
-   * Toggle the popover
-   */
-  toggle: (options?: FocusOptions) => void;
-}
-```

package/docs/index.md

@@ -1,24 +0,0 @@
----
-# https://vitepress.dev/reference/default-theme-home-page
-layout: home
-
-hero:
-  name: "Vue Composable UI"
-  text: "A truly headless UI framework"
-  tagline: My great project tagline
-  actions:
-    - theme: brand
-      text: Introduction
-      link: /intro
-    - theme: alt
-      text: API Examples
-      link: /api-examples
-
-features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
----

package/src/components/combobox/combobox.vue

@@ -1,229 +0,0 @@
-<template>
-  <template v-if="name">
-    <ComboboxFormInput
-      v-if="isMultiselectable"
-      v-for="(value, id) in formInputs"
-      :name="`${name}[${id}]`"
-      :value="value"
-    />
-    <ComboboxFormInput v-else :name="name" :value="formInputs" />
-  </template>
-
-  <slot
-    name="input"
-    :popoverId="popoverId"
-    :attrs="inputAttrs"
-    :isOpen="isOpen"
-    :toggle="toggle"
-  >
-    <input v-bind="{ ...$attrs, ...inputAttrs }" autocomplete="off" />
-  </slot>
-
-  <slot />
-</template>
-
-<script setup lang="ts">
-import { ref, computed, provide, watch, nextTick } from "vue";
-import { useSequentialId } from "../../utils/id";
-import { usePopover } from "../../composables/popover";
-import { useList } from "../../composables/list";
-import { useFormControl, FormValidator } from "../../composables/formControl";
-import ComboboxFormInput from "./comboboxFormInput.vue";
-import { injectCombobox } from "../injectionKeys";
-
-defineOptions({ inheritAttrs: false });
-
-const props = withDefaults(
-  defineProps<{
-    displayValue?: (value: any) => string;
-
-    id?: string;
-    activatorId?: string;
-
-    name?: string;
-    formValue?: (item: any) => Record<string, string> | string;
-
-    validators?: FormValidator[];
-    showValidationError?: boolean;
-  }>(),
-  {
-    displayValue: (value: any) =>
-      Array.isArray(value)
-        ? value.map((i) => i.toString()).join(", ")
-        : value.toString(),
-    formValue: (item: any) => item,
-    showValidationError: true,
-  }
-);
-
-const formInputs = computed(() => {
-  if (isMultiselectable.value) {
-    return (model.value as any[]).map((i) => props.formValue(i));
-  } else {
-    return props.formValue(model.value);
-  }
-});
-
-const model = defineModel();
-const modelIsValid = defineModel("isValid");
-const modelValidationMessage = defineModel("validationMessage");
-
-const comboboxId = props.id ?? useSequentialId("combobox");
-const activatorId = props.activatorId ?? comboboxId;
-const popoverId = `${comboboxId}-popover`;
-
-// Popover
-const { isOpen, toggle, open, close } = usePopover(
-  `#${activatorId}`,
-  `#${popoverId}`,
-  {
-    direction: "down",
-    align: "stretch",
-    position: "fixed",
-    closeOnOutsideClick: true,
-    closeOnInsideClick: false,
-  }
-);
-
-// List
-const {
-  items,
-  activeItem,
-  isMultiselectable,
-  selectActiveItem,
-  activateSelectedItem,
-  activateFirstItem,
-  activateLastItem,
-  activateNextItem,
-  activatePrevItem,
-} = useList(model);
-
-// Form Control
-const { focus, isValid, validationMessage } = useFormControl(
-  `#${comboboxId}`,
-  props.validators,
-  props.showValidationError
-);
-
-watch(isValid, () => (modelIsValid.value = isValid.value));
-watch(
-  validationMessage,
-  () => (modelValidationMessage.value = validationMessage.value)
-);
-
-watch(items, () => {
-  if (!activeItem.value && items.value.length) {
-    if (
-      (isMultiselectable.value && (model.value as any[]).length) ||
-      (!isMultiselectable.value && model.value)
-    ) {
-      activateSelectedItem({ focus: false });
-    } else {
-      activateFirstItem({ focus: false });
-    }
-  }
-});
-
-const inputValue = ref("");
-
-function updateInputValue() {
-  inputValue.value = props.displayValue(model.value);
-}
-
-watch(model, updateInputValue, { deep: true, immediate: true });
-
-function onChange() {
-  updateInputValue();
-}
-
-function onInput(evt: KeyboardEvent) {
-  inputValue.value = (evt.target as HTMLInputElement).value;
-  open({ focus: false });
-}
-
-function onKeyDown(evt: KeyboardEvent) {
-  if (!isOpen.value) {
-    switch (evt.code) {
-      case "Space":
-      case "Enter":
-        open({ focus: false });
-        break;
-
-      case "End":
-      case "ArrowUp":
-        open({ focus: false });
-        nextTick(() => activateLastItem({ focus: false }));
-        break;
-
-      case "Home":
-      case "ArrowDown":
-        open({ focus: false });
-        nextTick(() => activateFirstItem({ focus: false }));
-        break;
-
-      default:
-        return;
-    }
-  } else {
-    switch (evt.code) {
-      case "Space":
-        selectActiveItem();
-        if (!isMultiselectable.value) {
-          close();
-        }
-        break;
-      case "Enter":
-        selectActiveItem();
-        close();
-        break;
-      case "Tab":
-        selectActiveItem();
-        close();
-        return;
-      case "ArrowUp":
-        activatePrevItem({ focus: false, loop: false });
-        break;
-      case "ArrowDown":
-        activateNextItem({ focus: false, loop: false });
-        break;
-      case "Home":
-        activateFirstItem({ focus: false });
-        break;
-      case "End":
-        activateLastItem({ focus: false });
-        break;
-      case "Escape":
-        close();
-        break;
-      default:
-        return;
-    }
-  }
-
-  evt.preventDefault();
-}
-
-const inputAttrs = computed(() => ({
-  value: inputValue.value,
-  oninput: onInput,
-  onchange: onChange,
-  onkeydown: onKeyDown,
-  onclick: () => open({ focus: false }),
-  id: comboboxId,
-  "aria-controls": isOpen.value ? popoverId : undefined,
-  "aria-expanded": isOpen.value,
-  "aria-activedescendant": activeItem.value?.element.value?.id,
-  "aria-haspopup": "listbox" as "listbox",
-  role: "combobox",
-}));
-
-provide(injectCombobox, {
-  popoverId,
-  isOpen,
-  isMultiselectable,
-  close,
-  focus,
-});
-</script>
-
-<style scoped></style>

package/src/components/combobox/comboboxFormInput.vue

@@ -1,33 +0,0 @@
-<template>
-  <input
-    v-for="(value, name) in inputs"
-    :name="name"
-    :value="value"
-    type="hidden"
-  />
-</template>
-
-<script setup lang="ts">
-import { computed } from "vue";
-
-const props = defineProps<{
-  name: string;
-  value: any;
-}>();
-
-const inputs = computed(() => {
-  if (typeof props.value === "object") {
-    const fields: Record<string, any> = {};
-    for (const [key, value] of Object.entries(props.value)) {
-      fields[`${props.name}[${key}]`] = value;
-    }
-    return fields;
-  } else {
-    return {
-      [props.name]: props.value,
-    };
-  }
-});
-</script>
-
-<style scoped></style>

package/src/components/combobox/comboboxOption.vue

@@ -1,52 +0,0 @@
-<template>
-  <div
-    ref="itemEl"
-    :id="itemId"
-    @click="onClick"
-    @mouseenter="activate({ focus: false })"
-    :data-active="isActive"
-    :aria-selected="isSelected"
-    :aria-disabled="disabled || undefined"
-    role="option"
-  >
-    <slot :isSelected="isSelected" :isActive="isActive" />
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref, inject } from "vue";
-import { useSequentialId } from "../../utils/id";
-import { useListOption } from "../../composables/listOption";
-import { injectCombobox } from "../injectionKeys";
-
-const props = defineProps<{
-  id?: string;
-  value: any;
-  disabled?: boolean;
-}>();
-
-const itemId = props.id ?? useSequentialId("combobox-option");
-
-const itemEl = ref<HTMLElement>();
-
-const { isSelected, isActive, activate, select } = useListOption(
-  itemEl,
-  props.value,
-  props.disabled
-);
-
-const combobox = inject(injectCombobox);
-if (!combobox) {
-  throw new Error("Combobox injectable context is not provided");
-}
-
-function onClick() {
-  select();
-  if (!combobox!.isMultiselectable.value) {
-    combobox!.close({ focus: false });
-  }
-  combobox!.focus();
-}
-</script>
-
-<style scoped></style>

package/src/components/combobox/comboboxOptions.vue

@@ -1,17 +0,0 @@
-<template>
-  <div v-if="combobox!.isOpen.value" :id="combobox!.popoverId" role="listbox">
-    <slot />
-  </div>
-</template>
-
-<script setup lang="ts">
-import { inject } from "vue";
-import { injectCombobox } from "../injectionKeys";
-
-const combobox = inject(injectCombobox);
-if (!combobox) {
-  throw new Error("Combobox injectable context is not provided");
-}
-</script>
-
-<style scoped></style>

package/src/components/injectionKeys.ts

@@ -1,50 +0,0 @@
-import type { ComputedRef, InjectionKey } from "vue";
-
-import type { UseListReturn } from "../composables/list";
-import type { UsePopoverReturn } from "../composables/popover";
-import type { useFormControlReturn } from "../composables/formControl";
-
-export const injectTabs: InjectionKey<{
-  getIds: (value: any) => ComputedRef<{
-    tabId: string | undefined;
-    panelId: string | undefined;
-  }>;
-  selectActiveItem: UseListReturn["selectActiveItem"];
-  activateFirstItem: UseListReturn["activateFirstItem"];
-  activateLastItem: UseListReturn["activateLastItem"];
-  activateNextItem: UseListReturn["activateNextItem"];
-  activatePrevItem: UseListReturn["activatePrevItem"];
-  orientation: "horizontal" | "vertical";
-}> = Symbol();
-
-export const injectPopover: InjectionKey<{
-  popoverId: string;
-  activatorId: string;
-  role: "dialog" | "listbox" | "menu" | "tree" | "grid";
-  isOpen: UsePopoverReturn["isOpen"];
-  close: UsePopoverReturn["close"];
-}> = Symbol();
-
-export const injectMenu: InjectionKey<{
-  menuId: string;
-  activatorId: string;
-  isOpen: UsePopoverReturn["isOpen"];
-  close: UsePopoverReturn["close"];
-
-  activeItemId: ComputedRef<string | undefined>;
-  isMultiselectable: UseListReturn["isMultiselectable"];
-  activateFirstItem: UseListReturn["activateFirstItem"];
-  activateLastItem: UseListReturn["activateLastItem"];
-  activateNextItem: UseListReturn["activateNextItem"];
-  activatePrevItem: UseListReturn["activatePrevItem"];
-}> = Symbol();
-
-export const injectCombobox: InjectionKey<{
-  popoverId: string;
-  isOpen: UsePopoverReturn["isOpen"];
-  close: UsePopoverReturn["close"];
-
-  isMultiselectable: UseListReturn["isMultiselectable"];
-
-  focus: useFormControlReturn["focus"];
-}> = Symbol();