vue-composable-ui 0.0.1

package/docs/components/popover.md

@@ -0,0 +1,82 @@
+<script setup>
+import PopoverDemo from './demos/popover.vue'
+</script>
+
+# Popover Component
+
+Popover is a floating container that appears next to its activator element above the main document flow.
+
+No event listeners are attached to the activating element to give the user full control over the way the popover is triggered.
+
+Based on:
+
+- [usePopover](/composables/popover)
+
+## Demo
+
+<PopoverDemo />
+
+::: details Code
+<<< ./demos/popover.vue
+:::
+
+## Popover
+
+The root component.
+
+### Properties
+
+| Property                | Required | Description                                          | Type                                                                        | Default        |
+| ----------------------- | -------- | ---------------------------------------------------- | --------------------------------------------------------------------------- | -------------- |
+| **id**                  | false    | The ID of the popover dialog.                        | `string`                                                                    | Auto-generated |
+| **activatorId**         | false    | The ID of the activator element.                     | `string`                                                                    | Auto-generated |
+| **direction**           | false    | The direction of the popover.                        | `'up'` \| `'down'` \| `'left'` \| `'right'`                                 | `'down'`       |
+| **align**               | false    | The alignment of the popover.                        | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'center'` \| `'stretch'` | `'left'`       |
+| **position**            | false    | CSS position of the popover dialog.                  | `'fixed'` \| `'absolute'`                                                   | `'fixed'`      |
+| **closeOnOutsideClick** | false    | Close the popover on an click outside of the dialog. | `boolean`                                                                   | `true`         |
+| **closeOnInsideClick**  | false    | Close the popover on an click inside of the dialog.  | `boolean`                                                                   | `false`        |
+| **role**                | false    | The ARIA role of the popover                         | `'dialog'` \| `'listbox'` \| `'menu'` \| `'tree'` \| `'grid'`               | `'dialog'`     |
+
+### Slots
+
+#### default
+
+The `default` slot is used to provide an activating element and a [PopoverDialog](#popoverdialog). The slot passes the following properties:
+
+| Property | Description                                                  | Type           |
+| -------- | ------------------------------------------------------------ | -------------- |
+| attrs    | Required attributes that **must** be binded to the activator | `object`       |
+| isOpen   | The status of the popover                                    | `Ref<boolean>` |
+| toggle   | Toggle the popover                                           | `() => void`   |
+| open     | Open the popover and place focus on it                       | `() => void`   |
+| close    | Close the popover and return focus to the activator          | `() => void`   |
+
+```vue-html
+<Popover v-slot="{ attrs, toggle, close }">
+  <button @click="toggle" v-bind="attrs">Toggle</button>
+
+  <PopoverDialog>
+    <button @click="close()" >Close</button>
+  </PopoverDialog>
+</Popover>
+```
+
+### ARIA roles and attributes
+
+The following attributes are managed for the activator:
+
+- [aria-controls](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)
+- [aria-haspopup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup)
+- [aria-expanded](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)
+
+## PopoverDialog
+
+### Keyboard interactions
+
+- `Escape` - Closes the popover and returns focus to the activating element.
+
+### ARIA roles and attributes
+
+The popover container has the role provided in the popover properties and automatically manages the following attributes:
+
+- [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby)

package/docs/components/tabs.md

@@ -0,0 +1,9 @@
+<script setup>
+import TabsDemo from './demos/tabs.vue'
+</script>
+
+# Tabs Components
+
+## Demo
+
+<TabsDemo />

package/docs/components/tooltip.md

@@ -0,0 +1,78 @@
+<script setup>
+import TooltipDemo from './demos/tooltip.vue'
+</script>
+
+# Tooltip Component
+
+A tooltip is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus.
+
+A tooltip activator can be provided in the default slot:
+
+```vue
+<Tooltip text="Tooltip text" v-slot="{ attrs }">
+  <button v-bind="attrs">Activator</button>
+</Tooltip>
+```
+
+Or by setting a tooltip id and using it in the `aria-describedby` attribute on the activator:
+
+```vue
+<Tooltip id="tooltip-example" text="Tooltip text" />
+<button aria-describedby="tooltip-example">Activator</button>
+```
+
+Based on:
+
+- [usePopover](/composables/popover)
+
+## Demo
+
+<TooltipDemo />
+
+::: details Code
+<<< ./demos/tooltip.vue
+:::
+
+## Tooltip
+
+### Properties
+
+| Property      | Required | Description                                           | Type                                        | Default        |
+| ------------- | -------- | ----------------------------------------------------- | ------------------------------------------- | -------------- |
+| **text**      | false    | Tooltip text.                                         | `string`                                    | `undefined`    |
+| **delay**     | false    | The delay before showing the tooltip in milliseconds. | `number` \| `string`                        | `undefined`    |
+| **direction** | false    | The direction of the tooltip.                         | `'up'` \| `'down'` \| `'left'` \| `'right'` | `'up'`         |
+| **id**        | false    | The ID of the tooltip.                                | `string`                                    | auto-generated |
+
+### Slots
+
+#### default
+
+The `default` slot can be used to provide an activator. The slot provides the `attrs` attribute that must be binded to the activating element.
+
+```vue
+<Tooltip text="Tooltip text" v-slot="{ attrs }">
+  <button v-bind="attrs">Activator</button>
+</Tooltip>
+```
+
+#### content
+
+The `content` slot can be used to provide any custom html content for the tooltip.
+
+```vue
+<Tooltip>
+  <template #content>
+    Any custom html content 
+    <img src="..." />
+  </template>
+</Tooltip>
+```
+
+### Keyboard interactions
+
+- `Escape` - Hides the tooltip without preventing the default action.
+
+### ARIA roles and attributes
+
+Tooltips have the [tooltip](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role) role.

package/docs/composables/form-control.md

@@ -0,0 +1,130 @@
+# useFormControl
+
+`useFormControl` utilizes [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation) to enable custom validation constrains for a form control.
+
+## Basic Usage
+
+```vue
+<script setup>
+import { ref } from "vue";
+import { useFormControl } from "vue-composable-ui";
+
+const codeInput = ref();
+
+const code = ref("");
+const country = ref("");
+
+const validateCode = (value) => {
+  const constraints = {
+    ch: [
+      "^(CH-)?\\d{4}$",
+      "Swiss postal codes must have exactly 4 digits: e.g. CH-1950 or 1950",
+    ],
+    fr: [
+      "^(F-)?\\d{5}$",
+      "French postal codes must have exactly 5 digits: e.g. F-75012 or 75012",
+    ],
+    de: [
+      "^(D-)?\\d{5}$",
+      "German postal codes must have exactly 5 digits: e.g. D-12345 or 12345",
+    ],
+    nl: [
+      "^(NL-)?\\d{4}\\s*([A-RT-Z][A-Z]|S[BCE-RT-Z])$",
+      "Dutch postal codes must have exactly 4 digits, followed by 2 letters except SA, SD and SS",
+    ],
+  };
+
+  const constraint = new RegExp(constraints[country.value][0], "");
+
+  // Check it!
+  if (constraint.test(code.value)) {
+    // The postal code follows the constraint, we use the ConstraintAPI to tell it
+    return true;
+  } else {
+    // The postal code doesn't follow the constraint, we use the ConstraintAPI to
+    // give a message about the format required for this country
+    return constraints[country.value][1];
+  }
+};
+
+const { validate } = useFormControl(codeInput, [validateCode]);
+</script>
+
+<template>
+  <form>
+    <label for="postal-code">Postal Code: </label>
+    <input ref="codeInput" v-model="code" id="postal-code" />
+    <label for="country">Country: </label>
+    <select v-model="country" id="country">
+      <option value="ch">Switzerland</option>
+      <option value="fr">France</option>
+      <option value="de">Germany</option>
+      <option value="nl">The Netherlands</option>
+    </select>
+    <button type="button" @click="validate">Validate</button>
+  </form>
+</template>
+```
+
+## Type Declarations
+
+### Composable
+
+```ts
+type FormElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+
+/**
+ * A validating function must return `true` or a string describing the error
+ */
+export type FormValidator = (value: string) => boolean | string;
+
+/**
+ * Utilizes Constraint Validation API to enable custom validation constrains for a form control
+ *
+ * @param el A template ref or a CSS selector
+ * @param validators An array of validating functions
+ * @param showValidationError Whether to show the default browser validation error (true by default)
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation}
+ */
+export declare function useFormControl(
+  el: TemplateRefOrSelector<FormElement>,
+  validators?: MaybeRef<FormValidator[]>,
+  showValidationError?: MaybeRef<boolean>
+): useFormControlReturn;
+```
+
+### Return Type
+
+```ts
+export interface useFormControlReturn {
+  /**
+   * Focus the form control
+   */
+  focus: () => void;
+  /**
+   * Validate the form control
+   *
+   * @returns Validation result
+   */
+  validate: () => boolean;
+  /**
+   * Whether the form control is valid. A shorthand for `validity.valid`, but can be manually overriden.
+   */
+  isValid: Ref<boolean>;
+  /**
+   * The validity state of the form control
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState}
+   */
+  validity: Readonly<Ref<ValidityState | undefined>>;
+  /**
+   * A string representing a localized message that describes the validation constraints that the control does not satisfy (if any)
+   */
+  validationMessage: Readonly<Ref<string>>;
+  /**
+   * Whether the value has been changed since the form control was mounted
+   */
+  isChanged: Ref<boolean>;
+}
+```

package/docs/composables/list-option.md

@@ -0,0 +1,47 @@
+# useListOption
+
+`useListOption` is meant to be used in a child component representing a list item inside a parent component that uses the [`useList`](/composables/list) composable.
+
+See the [Basic Usage](/composables/list#basic-usage) example.
+
+## Type Declarations
+
+### Composable
+
+```ts
+/**
+ * Registers an HTML element and an associated value in the list created in the parent component
+ *
+ * @param el A template ref or a CSS selector
+ * @param value A value of any type to associate with the HTML element
+ * @param disabled Whether the item is disabled (false by default)
+ */
+export declare function useListOption(
+  el: HTMLElementType,
+  value: ItemValue,
+  disabled?: MaybeRef<boolean>
+): UseListOptionReturn;
+```
+
+### Return Type
+
+```ts
+interface UseListOptionReturn {
+  /**
+   * Whether the item is selected
+   */
+  isSelected: ComputedRef<boolean>;
+  /**
+   * Whether the item is active
+   */
+  isActive: ComputedRef<boolean>;
+  /**
+   * Select the item
+   */
+  select: () => void;
+  /**
+   * Activate the item
+   */
+  activate: () => void;
+}
+```

package/docs/composables/list.md

@@ -0,0 +1,192 @@
+# 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

@@ -0,0 +1,90 @@
+# 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

@@ -0,0 +1,24 @@
+---
+# 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/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "vue-composable-ui",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": "https://github.com/dzapletin/vue-composable-ui",
+  "main": "./dist/composable-ui.umd.cjs",
+  "module": "./dist/composable-ui.js",
+  "exports": {
+    ".": {
+      "import": "./dist/composable-ui.js",
+      "require": "./dist/composable-ui.umd.cjs"
+    }
+  },
+  "types": "./dist/types/main.d.ts",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && vue-tsc",
+    "preview": "vite preview",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "vue": "^3.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.4.0",
+    "@vitejs/plugin-vue": "^5.1.2",
+    "sass": "^1.69.5",
+    "typescript": "^5.0.2",
+    "vite": "^5.4.1",
+    "vitepress": "^1.0.0-rc.24",
+    "vue-tsc": "^2.0.29"
+  }
+}