@poppy-ui/vue 0.5.6 → 0.5.7-beta.0

package/src/components/data/select/Select.vue

@@ -0,0 +1,329 @@
+<script lang="ts">
+import { Badge } from '@/components/display/public'
+import { useComponentConfig } from '@/composables/use-component-config'
+import { useFormField } from '@/composables/use-form-field'
+import { useSelectCounter } from '@/composables/use-select-counter'
+import { getClass } from '@/utils/build-class.util'
+import { ChevronDownIcon, XIcon } from '@lucide/vue'
+import { onClickOutside } from '@vueuse/core'
+import { computed, shallowRef, useAttrs, useId, useTemplateRef } from 'vue'
+import { SELECT_CONFIG } from './select.context'
+import type { SelectProps } from './select.props'
+import type { SelectColor, SelectOption, SelectSize, SelectVariant } from './select.types'
+
+const selectColors: Record<SelectColor, `select-${SelectColor}`> = {
+  neutral: 'select-neutral',
+  primary: 'select-primary',
+  secondary: 'select-secondary',
+  accent: 'select-accent',
+  info: 'select-info',
+  success: 'select-success',
+  warning: 'select-warning',
+  error: 'select-error',
+}
+
+const selectSizes: Record<SelectSize, `select-${SelectSize}`> = {
+  xs: 'select-xs',
+  sm: 'select-sm',
+  md: 'select-md',
+  lg: 'select-lg',
+  xl: 'select-xl',
+}
+
+const selectVariants: Record<SelectVariant, `select-${SelectVariant}`> = {
+  bordered: 'select-bordered',
+  ghost: 'select-ghost',
+}
+</script>
+
+<script setup lang="ts" generic="T = any, M extends boolean = false">
+type ModelType = M extends true ? T[] : T | undefined
+
+defineOptions({ inheritAttrs: false })
+
+const emit = defineEmits<{
+  clear: []
+}>()
+
+const containerEl = useTemplateRef('containerEl')
+const triggerEl = useTemplateRef('triggerEl')
+
+const model = defineModel<ModelType>()
+const props = defineProps<SelectProps<T, M>>()
+
+// @ts-expect-error - Ignored due to the genereic in script
+const config = useComponentConfig(SELECT_CONFIG, props, {
+  size: 'md',
+  clearable: false,
+})
+
+const anchorName = `--select-anchor-${useId()}`
+const attrs = useAttrs()
+const isOpen = shallowRef(false)
+
+const { field, fieldValue, hasServerError, onBlur, clearError } = useFormField<ModelType>({
+  required: computed(() => props.required ?? false),
+})
+
+onClickOutside(containerEl, () => {
+  if (isOpen.value) {
+    isOpen.value = false
+    onBlur()
+  }
+})
+
+const value = computed(() => field ? fieldValue.value : model.value)
+
+const minItems = computed(() => (attrs.min ? Number(attrs.min) : undefined))
+const maxItems = computed(() => (attrs.max ? Number(attrs.max) : undefined))
+
+const selectedCount = computed(() => {
+  if (!props.multiple || !Array.isArray(value.value)) return 0
+  return (value.value as T[]).length
+})
+
+const { counterText, counterColor, isAtMax } = useSelectCounter(selectedCount, {
+  multiple: computed(() => props.multiple),
+  min: minItems,
+  max: maxItems,
+  formatter: computed(() => config.value.counterFormatter),
+})
+
+const hasValue = computed(() => {
+  if (props.multiple) {
+    return Array.isArray(value.value) && (value.value as T[]).length > 0
+  }
+  return value.value !== undefined && value.value !== null && value.value !== ''
+})
+
+const selectedOptions = computed(() => {
+  if (!props.options) return []
+  const current = value.value
+  if (!current) return []
+  if (props.multiple && Array.isArray(current)) {
+    return props.options.filter(o => (current as T[]).some(v => isEqual(o.value, v)))
+  }
+  const found = props.options.find(o => isEqual(o.value, current as T))
+  return found ? [found] : []
+})
+
+function isEqual(a: T, b: T): boolean {
+  if (!props.equals) return a === b
+  if (typeof props.equals === 'function') return (props.equals as (a: T, b: T) => boolean)(a, b)
+  return (a as any)?.[props.equals] === (b as any)?.[props.equals]
+}
+
+function isOptionSelected(option: SelectOption<T>): boolean {
+  const current = value.value
+  if (props.multiple && Array.isArray(current)) {
+    return (current as T[]).some(v => isEqual(v, option.value))
+  }
+  return isEqual(current as T, option.value)
+}
+
+function isOptionDisabled(option: SelectOption<T>): boolean {
+  return isAtMax.value && !isOptionSelected(option)
+}
+
+function setValue(next: ModelType): void {
+  model.value = next
+  if (field) {
+    field.setValue(next)
+    field.setDirty(true)
+    clearError()
+  }
+}
+
+function select(option: SelectOption<T>): void {
+  if (isOptionDisabled(option)) return
+
+  if (props.multiple) {
+    const current = (Array.isArray(value.value) ? value.value : []) as T[]
+    const exists = current.some(v => isEqual(v, option.value))
+    const next = exists
+      ? current.filter(v => !isEqual(v, option.value))
+      : [...current, option.value]
+    setValue(next as ModelType)
+    return
+  }
+
+  if (isOptionSelected(option)) {
+    if (config.value.clearable) {
+      setValue(undefined as ModelType)
+      isOpen.value = false
+    }
+    return
+  }
+
+  setValue(option.value as ModelType)
+  isOpen.value = false
+}
+
+function removeSelected(option: SelectOption<T>): void {
+  if (!props.multiple) return
+  const current = (Array.isArray(value.value) ? value.value : []) as T[]
+  setValue(current.filter(v => !isEqual(v, option.value)) as ModelType)
+}
+
+function onClear(): void {
+  setValue((props.multiple ? [] : undefined) as ModelType)
+  emit('clear')
+}
+
+function open(): void {
+  if (props.disabled) return
+  isOpen.value = true
+}
+
+function close(): void {
+  if (props.disabled) return
+  isOpen.value = false
+}
+
+function toggle(): void {
+  isOpen.value ? close() : open()
+}
+
+defineExpose({
+  $el: triggerEl,
+  clear: onClear,
+  open,
+  close,
+  toggle,
+})
+</script>
+
+<template>
+  <div class="w-full flex flex-col gap-1">
+    <div ref="containerEl" class="relative w-full anchor-trigger" v-bind="$attrs">
+      <input type="hidden" :name="field?.name ?? name" :value="(model as any)" />
+
+      <button
+        ref="triggerEl"
+        type="button"
+        class="select w-full text-left min-h-10 h-auto py-2 pr-10"
+        :class="[
+          getClass(selectColors, config.color),
+          getClass(selectSizes, config.size),
+          getClass(selectVariants, config.variant),
+          disabled && 'select-disabled',
+          hasServerError && 'select-error',
+        ]"
+        :tabindex="disabled ? '-1' : undefined"
+        :disabled="disabled"
+        @click="toggle()"
+      >
+        <div v-if="multiple && selectedOptions.length > 0" class="flex flex-wrap gap-1">
+          <slot
+            v-for="opt in selectedOptions"
+            :key="String(opt.value)"
+            name="selected"
+            :option="opt"
+            :remove="() => removeSelected(opt)"
+          >
+            <Badge color="primary" size="sm" class="gap-1 cursor-default">
+              {{ opt.label }}
+              <button
+                type="button"
+                class="hover:opacity-70"
+                @click.stop="removeSelected(opt)"
+              >
+                <XIcon class="size-3" />
+              </button>
+            </Badge>
+          </slot>
+        </div>
+
+        <template v-else-if="!multiple && selectedOptions.length > 0">
+          <slot name="selected" :option="selectedOptions[0]" :remove="onClear">
+            <span>{{ selectedOptions[0]?.label }}</span>
+          </slot>
+        </template>
+
+        <span v-else class="opacity-40">
+          {{ placeholder || $t('common.field.select.placeholder') }}
+        </span>
+      </button>
+
+      <ChevronDownIcon
+        class="absolute right-3 top-1/2 -translate-y-1/2 size-4 opacity-40 pointer-events-none transition-transform"
+        :class="isOpen && 'rotate-180'"
+      />
+
+      <button
+        v-if="config.clearable && hasValue"
+        type="button"
+        class="absolute right-8 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle opacity-50 hover:opacity-100"
+        @click="onClear"
+      >
+        <XIcon class="size-3" />
+      </button>
+
+      <Transition name="dropdown">
+        <div
+          v-if="isOpen && options"
+          class="anchor-dropdown absolute z-50 w-full bg-base-100 border border-base-300 rounded-box shadow-lg overflow-hidden"
+        >
+          <ul class="max-h-56 overflow-y-auto py-1">
+            <li
+              v-for="option in options"
+              :key="String(option.value)"
+              class="px-4 py-2 text-sm cursor-pointer hover:bg-base-200"
+              :class="[
+                isOptionSelected(option) && 'bg-primary/10 text-primary',
+                isOptionDisabled(option) && 'opacity-30 cursor-not-allowed pointer-events-none',
+              ]"
+              @mousedown.prevent="select(option)"
+            >
+              <slot name="option" :option="option" :selected="isOptionSelected(option)">
+                {{ option.label }}
+              </slot>
+            </li>
+
+            <li v-if="options.length === 0" class="px-4 py-3 text-sm opacity-40 text-center">
+              {{ $t('common.field.select.empty') }}
+            </li>
+          </ul>
+        </div>
+      </Transition>
+    </div>
+
+    <div v-if="multiple && counterText" class="flex justify-end">
+      <span class="text-xs" :class="counterColor">{{ counterText }}</span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.select {
+  background-image: initial;
+  background-position: initial;
+  background-size: initial;
+  background-repeat: initial;
+}
+
+.anchor-trigger {
+  anchor-name: v-bind(anchorName);
+}
+
+.anchor-dropdown {
+  position-anchor: v-bind(anchorName);
+  position-area: block-end center;
+  position-try-fallbacks: flip-block, flip-inline;
+  position-try-order: most-height;
+  left: anchor(left);
+  right: anchor(right);
+  margin-block-start: 4px;
+}
+
+.dropdown-enter-active,
+.dropdown-leave-active {
+  transition: opacity 0.15s ease, transform 0.15s ease;
+}
+
+.dropdown-enter-from,
+.dropdown-leave-to {
+  opacity: 0;
+  transform: translateY(-4px);
+}
+</style>

package/src/components/data/select/select.context.ts

@@ -0,0 +1,3 @@
+import { createComponentConfigKey } from '@/symbol'
+
+export const SELECT_CONFIG = createComponentConfigKey('select')

package/src/components/data/select/select.props.ts

@@ -0,0 +1,65 @@
+import type { SelectCounterFormatter } from '@/composables/use-select-counter'
+import type { EqualsArg, SelectColor, SelectOption, SelectSize, SelectVariant } from './select.types'
+
+export interface SelectConfigurableProps {
+  /**
+   * Color variant of the select.
+   */
+  color?: SelectColor
+
+  /**
+   * Visual style variant.
+   * - `'bordered'` — adds a visible border
+   * - `'ghost'` — transparent background
+   */
+  variant?: SelectVariant
+
+  /**
+   * Size of the select.
+   *
+   * @default 'md'
+   */
+  size?: SelectSize
+
+  /**
+   * Allows clearing the selection via a clear button.
+   * In single mode, clicking the active option also clears when enabled.
+   *
+   * @default false
+   */
+  clearable?: boolean
+
+  /**
+   * Custom counter format function.
+   * Receives `(count, min?, max?)` and returns a display string.
+   */
+  counterFormatter?: SelectCounterFormatter
+}
+
+export interface SelectProps<T = any, M extends boolean = false> extends SelectConfigurableProps {
+  /** Field name. Inferred from `<FormField />` name when not provided. */
+  name?: string
+  /** Disables all interaction. */
+  disabled?: boolean
+  /** Marks the field as required — signals `<FormField />` to display `"*"`. */
+  required?: boolean
+  /** Makes the select read-only. */
+  readonly?: boolean
+  /** Text shown when no value is selected. */
+  placeholder?: string
+  /** List of options to display. */
+  options?: SelectOption<T>[]
+  /**
+   * Key or function used for value equality comparison.
+   * Use a string key for objects, or a function for custom logic.
+   *
+   * @example 'id'
+   * @example (a, b) => a.id === b.id
+   */
+  equals?: EqualsArg<T>
+  /**
+   * Enables multiple selection.
+   * Not configurable globally — would break `T`/`M` type inference.
+   */
+  multiple?: M & boolean
+}

package/src/components/data/select/select.types.ts

@@ -0,0 +1,13 @@
+import type { ComponentSize } from '@/types/size.type'
+
+export type SelectOption<T> = {
+  value: T
+  label: string
+}
+
+export type SelectColor = 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error'
+export type SelectVariant = 'bordered' | 'ghost'
+export type SelectSize = ComponentSize
+
+export type EqualsArgFn<T> = (a: T, b: T) => boolean
+export type EqualsArg<T> = keyof T | EqualsArgFn<T>

package/src/components/data/slider/Slider.story.vue

@@ -0,0 +1,276 @@
+<script lang="ts">
+import Form from '@/components/data/form/Form.vue'
+import FormField from '@/components/data/form-field/FormField.vue'
+import { reactive, ref, shallowRef } from 'vue'
+import { createI18n } from 'vue-i18n'
+import Slider from './Slider.vue'
+import type { SliderProps } from './slider.props'
+</script>
+
+<script setup lang="ts">
+const singleValue = shallowRef<number>(50)
+const rangeValue = shallowRef<[number, number]>([20, 70])
+const noSwapValue = shallowRef<[number, number]>([30, 60])
+const invertedTrackValue = shallowRef<number>(50)
+const invertedRangeValue = shallowRef<[number, number]>([25, 75])
+const scaleValue = shallowRef<number>(50)
+
+// Scale function example: map 0-100 to 20-20000 (like frequency)
+function frequencyScale(value: number): number {
+  return 20 + (value / 100) * 19980
+}
+
+const state = reactive<SliderProps>({
+  size: 'md',
+  min: 0,
+  max: 100,
+  step: 1,
+  track: 'normal',
+  disableSwap: false,
+})
+
+const formData = ref<Record<string, unknown>>({ 
+  volume: 50,
+  priceRange: [20, 80],
+})
+</script>
+
+<template>
+  <Story group="components" title="Data/Slider" auto-props-disabled :setup-app="({ app }) => {
+    app.use(createI18n({}))
+  }" :layout="{ type: 'single', iframe: false }">
+
+    <Variant title="Default" id="default">
+      <template #controls>
+        <HstSelect
+          v-model="state.color"
+          title="color"
+          :options="[{ label: '-- default --', value: undefined }, 'neutral', 'primary', 'secondary', 'accent', 'info', 'success', 'warning', 'error']"
+        />
+        <HstSelect
+          v-model="state.size"
+          title="size"
+          :options="['xs', 'sm', 'md', 'lg', 'xl']"
+        />
+        <HstSlider v-model="state.min" title="min" :min="-100" :max="0" />
+        <HstSlider v-model="state.max" title="max" :min="0" :max="200" />
+        <HstSlider v-model="state.step" title="step" :min="1" :max="20" />
+        <HstSelect
+          v-model="state.track"
+          title="track"
+          :options="['normal', 'inverted', false]"
+        />
+        <HstCheckbox v-model="(state.disableSwap as boolean)" title="disableSwap" />
+        <HstCheckbox v-model="state.disabled" title="disabled" />
+      </template>
+
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="singleValue" v-bind="state" aria-label="Volume" />
+        <span class="text-sm opacity-60">Value: {{ singleValue }}</span>
+      </div>
+    </Variant>
+
+    <Variant title="Range Mode" id="range">
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="rangeValue" range color="primary" />
+        <span class="text-sm opacity-60">{{ rangeValue[0] }} – {{ rangeValue[1] }}</span>
+      </div>
+    </Variant>
+
+    <Variant title="Disable Swap" id="disable-swap">
+      <div class="p-4 flex flex-col gap-4">
+        <p class="text-sm opacity-60">Try to cross the thumbs - they will be blocked.</p>
+        <Slider v-model="noSwapValue" range :disable-swap="true" color="warning" />
+        <span class="text-sm opacity-60">{{ noSwapValue[0] }} – {{ noSwapValue[1] }}</span>
+      </div>
+    </Variant>
+
+    <Variant title="Swap Allowed (Default)" id="swap-allowed">
+      <div class="p-4 flex flex-col gap-4">
+        <p class="text-sm opacity-60">Try to cross the thumbs - they will swap roles transparently.</p>
+        <Slider v-model="rangeValue" range :disable-swap="false" color="success" />
+        <span class="text-sm opacity-60">{{ rangeValue[0] }} – {{ rangeValue[1] }}</span>
+      </div>
+    </Variant>
+
+    <Variant title="Track: Normal" id="track-normal">
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="singleValue" track="normal" color="primary" />
+        <span class="text-sm opacity-60">Track between min and thumb</span>
+      </div>
+    </Variant>
+
+    <Variant title="Track: Inverted" id="track-inverted">
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="invertedTrackValue" track="inverted" color="secondary" />
+        <span class="text-sm opacity-60">Track on unselected area</span>
+      </div>
+    </Variant>
+
+    <Variant title="Track: None" id="track-none">
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="singleValue" track="none" color="neutral" />
+        <span class="text-sm opacity-60">No track displayed</span>
+      </div>
+    </Variant>
+
+    <Variant title="Track Inverted (Range)" id="track-inverted-range">
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="invertedRangeValue" range track="inverted" color="error" />
+        <span class="text-sm opacity-60">{{ invertedRangeValue[0] }} – {{ invertedRangeValue[1] }}</span>
+      </div>
+    </Variant>
+
+    <Variant title="Scale Function" id="scale">
+      <div class="p-4 flex flex-col gap-2">
+        <Slider v-model="scaleValue" :scale="frequencyScale" :min="0" :max="100" color="info" />
+        <span class="text-sm opacity-60">Mechanical: {{ scaleValue }} | Business: {{ frequencyScale(scaleValue) }}Hz</span>
+      </div>
+    </Variant>
+
+    <Variant title="Colors" id="colors">
+      <div class="flex flex-col gap-6 p-4">
+        <Slider v-model="singleValue" color="neutral" />
+        <Slider v-model="singleValue" color="primary" />
+        <Slider v-model="singleValue" color="secondary" />
+        <Slider v-model="singleValue" color="accent" />
+        <Slider v-model="singleValue" color="info" />
+        <Slider v-model="singleValue" color="success" />
+        <Slider v-model="singleValue" color="warning" />
+        <Slider v-model="singleValue" color="error" />
+      </div>
+    </Variant>
+
+    <Variant title="Sizes" id="sizes">
+      <div class="flex flex-col gap-6 p-4">
+        <Slider v-model="singleValue" size="xs" />
+        <Slider v-model="singleValue" size="sm" />
+        <Slider v-model="singleValue" size="md" />
+        <Slider v-model="singleValue" size="lg" />
+        <Slider v-model="singleValue" size="xl" />
+      </div>
+    </Variant>
+
+    <Variant title="Disabled" id="disabled">
+      <div class="flex flex-col gap-6 p-4">
+        <Slider :value="40" disabled />
+        <Slider :value="[20, 70]" range disabled />
+      </div>
+    </Variant>
+
+    <Variant title="Inside FormField" id="inside-form-field">
+      <Form v-model="formData">
+        <FormField name="volume" label="Volume">
+          <Slider :min="0" :max="100" required aria-label="Volume level" />
+        </FormField>
+        <FormField name="priceRange" label="Price range" class="mt-4">
+          <Slider :min="0" :max="500" :step="10" range aria-label="Price range" />
+        </FormField>
+      </Form>
+    </Variant>
+
+  </Story>
+</template>
+
+<docs lang="md">
+# Slider
+
+## Description
+A custom slider component that allows users to select a value or range of values within a specified range. Based on the Range component with additional features like track inversion, thumb swapping control, and value scaling.
+
+## API
+
+### v-model
+
+| Name         | Type                         | Description                                                                        |
+|--------------|------------------------------|------------------------------------------------------------------------------------|
+| `modelValue` | `number \| [number, number]` | Single value, or `[low, high]` tuple in range mode. Values are always kept sorted. |
+
+### Props
+
+| Prop          | Type          | Default     | Description                                           |
+|---------------|---------------|-------------|-------------------------------------------------------|
+| `color`       | `SliderColor` | `undefined` | Color of the track fill and thumb border.             |
+| `size`        | `SliderSize`  | `'md'`      | Size of the slider (track height and thumb diameter). |
+| `min`         | `number`      | `0`         | Minimum value.                                        |
+| `max`         | `number`      | `100`       | Maximum value.                                        |
+| `step`        | `number`      | `1`         | Step increment.                                       |
+| `track`       | `SliderTrack` | `'normal'`  | Track display mode.                                   |
+| `range`       | `boolean`     | `false`     | Enables double thumb mode.                            |
+| `disableSwap` | `boolean`     | `false`     | Prevents thumbs from crossing/swapping.               |
+| `scale`       | `SliderScale` | `undefined` | Function to transform mechanical to business values.  |
+| `disabled`    | `boolean`     | `false`     | Disables all interaction.                             |
+| `required`    | `boolean`     | `undefined` | Native required.                                      |
+| `ariaLabel`   | `string`      | `undefined` | Accessible label for the slider.                      |
+
+### Events
+
+| Event                | Payload                      | Description                                                |
+|----------------------|------------------------------|------------------------------------------------------------|
+| `@input`             | `number \| [number, number]` | Emitted on every value change during interaction.          |
+| `@change`            | `number \| [number, number]` | Emitted when interaction ends (mouse up, touch end, blur). |
+
+## Note
+
+### Features
+- **Single or Range Mode**: Support for single value selection or dual-thumb range selection
+- **Track Modes**: Normal (selected area), Inverted (unselected area), or none
+- **Thumb Swapping**: Configurable behavior when thumbs cross (allow swap or prevent)
+- **Value Scaling**: Transform mechanical values to business values via scale function
+- **Keyboard Navigation**: Full keyboard support (Arrow keys, Page Up/Down, Home/End)
+- **Accessibility**: ARIA compliant with proper roles, states, and labels
+- **Form Integration**: Works seamlessly with FormField
+
+### Track Modes
+| Mode       | Behavior                                                                 |
+|------------|--------------------------------------------------------------------------|
+| `normal`   | Track fills between min and thumb (or between both thumbs in range mode) |
+| `inverted` | Track fills the unselected area                                          |
+| `false`    | No track is displayed                                                    |
+
+### Swap Behavior
+
+| disableSwap       | Behavior                                                                                                                    |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------|
+| `false` (default) | Thumbs can cross and swap roles - the left thumb becomes the right one and vice versa. The swap is transparent to the user. |
+| `true`            | Thumbs cannot cross - they are clamped to prevent crossing.                                                                 |
+
+### Scale Function
+
+The scale function transforms mechanical values (in min-max range) to business values.
+The mechanical values are used for positioning, while the scaled values are emitted and displayed.
+
+```typescript
+// Example: Map 0-100 to 20-20000 (frequency)
+const frequencyScale = (value: number) => 20 + (value / 100) * 19980
+
+// Example: Map 0-100 to -50 to +50 (temperature)
+const temperatureScale = (value: number) => value - 50
+```
+
+## Usage
+```vue
+<!-- Basic slider -->
+<Slider v-model="volume" :min="0" :max="100" />
+
+<!-- Range slider -->
+<Slider v-model="priceRange" range :min="0" :max="500" :step="10" />
+
+<!-- Inverted track -->
+<Slider v-model="value" track="inverted" />
+
+<!-- No track -->
+<Slider v-model="value" :track="false" />
+
+<!-- Prevent thumb swapping -->
+<Slider v-model="[min, max]" range disable-swap />
+
+<!-- With scale function (frequency) -->
+<Slider v-model="freq" :scale="v => 20 + (v/100)*19980" :min="0" :max="100" />
+
+<!-- Inside FormField -->
+<FormField name="budget" label="Budget range">
+  <Slider v-model="budget" range :min="0" :max="1000" :step="50" />
+</FormField>
+```
+</docs>