frappe-ui 1.0.0-beta.2 → 1.0.0-beta.21

package/src/molecules/list/List.vue

@@ -0,0 +1,93 @@
+<template>
+  <div data-slot="list" :role="hasHeader ? 'table' : 'list'" :style="style">
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, getCurrentInstance, ref } from 'vue'
+import { provideListContext } from './list-context'
+import type { ListProps } from './types'
+
+const props = defineProps<ListProps>()
+
+const selection = defineModel<string[]>('selection', { default: () => [] })
+// Single active row. Unlike `selection` there's no explicit mode flag: binding
+// v-model:active is the opt-in, detected via the update listener below so a
+// highlight never appears on a list that doesn't track one.
+const active = defineModel<string | undefined>('active')
+
+const instance = getCurrentInstance()
+const activatable = computed(
+  () => 'onUpdate:active' in (instance?.vnode.props ?? {}),
+)
+
+const hasHeader = ref(false)
+
+const style = computed(() => ({
+  ...(props.columns ? { '--list-columns-default': props.columns.join(' ') } : {}),
+  ...(props.selectable ? { '--list-checkbox-width': '32px' } : {}),
+  ...(props.rowHeight ? { '--list-row-height': `${props.rowHeight}px` } : {}),
+}))
+
+function isSelected(value: string) {
+  return selection.value.includes(value)
+}
+
+function toggleSelection(value: string) {
+  selection.value = isSelected(value)
+    ? selection.value.filter((selected) => selected !== value)
+    : [...selection.value, value]
+}
+
+function isActive(value: string) {
+  return active.value === value
+}
+
+function activate(value: string) {
+  active.value = value
+}
+
+// The full set of selectable row values, fed by <ListRows>. Drives the header
+// select-all without depending on which rows are currently mounted.
+const allValues = ref<string[]>([])
+function setAllValues(values: string[]) {
+  allValues.value = values
+}
+
+const selectAllState = computed<'none' | 'some' | 'all'>(() => {
+  const universe = allValues.value
+  if (!universe.length) return 'none'
+  const selectedCount = universe.filter((value) =>
+    selection.value.includes(value),
+  ).length
+  if (selectedCount === 0) return 'none'
+  return selectedCount === universe.length ? 'all' : 'some'
+})
+
+function toggleSelectAll() {
+  if (selectAllState.value === 'all') {
+    // Clear only the current universe; preserve any selected values outside it
+    // (e.g. carried over from a previous filter or page).
+    const universe = new Set(allValues.value)
+    selection.value = selection.value.filter((value) => !universe.has(value))
+  } else {
+    selection.value = [...new Set([...selection.value, ...allValues.value])]
+  }
+}
+
+provideListContext({
+  divider: computed(() => props.divider ?? (props.columns ? 'full' : 'inset')),
+  selectable: computed(() => !!props.selectable),
+  rowHeight: computed(() => props.rowHeight),
+  hasHeader,
+  isSelected,
+  toggleSelection,
+  activatable,
+  isActive,
+  activate,
+  setAllValues,
+  selectAllState,
+  toggleSelectAll,
+})
+</script>

package/src/molecules/list/ListCell.vue

@@ -0,0 +1,15 @@
+<template>
+  <div
+    data-slot="list-cell"
+    :role="context?.hasHeader.value ? 'cell' : undefined"
+    class="flex min-w-0 items-center"
+  >
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useListContext } from './list-context'
+
+const context = useListContext()
+</script>

package/src/molecules/list/ListGroup.vue

@@ -0,0 +1,40 @@
+<template>
+  <!-- A titled section of rows. `role="rowgroup"` gives assistive tech real
+       group structure, and keeping the rows as direct children preserves the
+       family's `list-row + list-row` divider adjacency *within* the group —
+       something a raw <p> spliced between rows silently breaks. -->
+  <div data-slot="list-group" role="rowgroup" :aria-label="ariaLabel">
+    <div
+      v-if="label || $slots.header"
+      data-slot="list-group-header"
+      class="flex h-8 items-center text-sm-medium text-ink-gray-5"
+      :class="sticky && 'sticky top-0 z-10 bg-surface-base'"
+    >
+      <slot name="header">{{ label }}</slot>
+    </div>
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  /** Section label shown in the group header. Overridden by the #header slot. */
+  label?: string
+  /**
+   * Pin the group header to the top of the scroll container while its rows
+   * scroll under it. Off by default.
+   */
+  sticky?: boolean
+}>()
+
+defineSlots<{
+  /** The group's rows — `<ListRow>` elements. */
+  default?: () => unknown
+  /** Replaces the header content (the label). */
+  header?: () => unknown
+}>()
+
+const ariaLabel = computed(() => props.label || undefined)
+</script>

package/src/molecules/list/ListHeader.vue

@@ -0,0 +1,62 @@
+<template>
+  <div data-slot="list-header" role="row" class="h-8 text-sm text-ink-gray-5">
+    <slot />
+    <Transition
+      enter-active-class="transition-transform duration-75 ease-out"
+      leave-active-class="transition-transform duration-75 ease-out"
+      enter-from-class="scale-0"
+      leave-to-class="scale-0"
+    >
+      <div
+        v-if="context?.selectable.value"
+        data-slot="list-header-checkbox"
+        role="checkbox"
+        :aria-checked="ariaChecked"
+        aria-label="Select all"
+        tabindex="0"
+        @click.stop.prevent="context.toggleSelectAll"
+        @keydown.enter.prevent="context.toggleSelectAll"
+        @keydown.space.prevent="context.toggleSelectAll"
+      >
+        <!-- Presentational; the wrapper div is the real role=checkbox control.
+             See ListRowBase for why pointer-events-none matters. -->
+        <Checkbox
+          :modelValue="context.selectAllState.value === 'all'"
+          :indeterminate="context.selectAllState.value === 'some'"
+          tabindex="-1"
+          aria-hidden="true"
+          class="pointer-events-none"
+        />
+      </div>
+    </Transition>
+    <div
+      data-slot="list-header-border"
+      aria-hidden="true"
+      class="border-b border-outline-gray-1"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount } from 'vue'
+import Checkbox from '../../components/Checkbox/Checkbox.vue'
+import { useListContext } from './list-context'
+
+const context = useListContext()
+
+const ariaChecked = computed(() => {
+  const state = context?.selectAllState.value
+  if (state === 'all') return 'true'
+  if (state === 'some') return 'mixed'
+  return 'false'
+})
+
+// Header presence is the signal that flips the List into table semantics
+// (role table/row/columnheader/cell) — there is no mode prop.
+if (context) {
+  context.hasHeader.value = true
+  onBeforeUnmount(() => {
+    context.hasHeader.value = false
+  })
+}
+</script>

package/src/molecules/list/ListHeaderCell.vue

@@ -0,0 +1,26 @@
+<template>
+  <div
+    data-slot="list-header-cell"
+    role="columnheader"
+    class="flex min-w-0 items-center gap-1"
+  >
+    <span v-if="$slots.prefix" class="shrink-0">
+      <slot name="prefix" />
+    </span>
+    <span class="truncate"><slot /></span>
+    <span v-if="$slots.suffix" class="shrink-0">
+      <slot name="suffix" />
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineSlots<{
+  /** Column label. */
+  default?: () => unknown
+  /** Leading adornment, rendered before the label. */
+  prefix?: () => unknown
+  /** Trailing adornment, rendered after the label. */
+  suffix?: () => unknown
+}>()
+</script>

package/src/molecules/list/ListHeaderCellSort.vue

@@ -0,0 +1,106 @@
+<template>
+  <div
+    data-slot="list-header-cell"
+    role="columnheader"
+    :aria-sort="
+      direction ? (direction === 'asc' ? 'ascending' : 'descending') : undefined
+    "
+    :data-sort="direction || undefined"
+    class="flex min-w-0 items-center"
+    :class="isEnd && 'justify-end'"
+  >
+    <!-- Controlled: sort state and toggle rules live in the app, surfaced
+         back via `direction`. The cell renders only the behavioral chrome —
+         real button, aria-sort, tooltip, suffix reveal. -->
+    <Tooltip :text="tooltipText" :disabled="!tooltipText">
+      <button
+        ref="button"
+        type="button"
+        class="group inline-flex h-7 min-w-0 items-center gap-1 rounded text-sm-medium text-ink-gray-5 transition-colors"
+        @click="emit('click', $event)"
+      >
+        <!-- End-aligned: the glyph leads so the label stays flush with the
+             column's right edge (aligned with the values below). A trailing
+             glyph would reserve space and push the label off the edge. -->
+        <span
+          v-if="isEnd"
+          class="shrink-0"
+          :class="suffixRevealClass"
+          aria-hidden="true"
+        >
+          <slot name="suffix" :direction="direction ?? null">
+            <span class="block size-3.5" :class="defaultArrowClass" />
+          </slot>
+        </span>
+        <span v-if="$slots.prefix" class="shrink-0">
+          <slot name="prefix" :direction="direction ?? null" />
+        </span>
+        <span class="truncate"><slot /></span>
+        <!-- A built-in arrow derived from `direction` by default, so the common
+             case needs no glyph wiring; supply #suffix to override. The cell
+             owns the reveal: an inactive column's glyph shows on hover. -->
+        <span
+          v-if="!isEnd"
+          class="shrink-0"
+          :class="suffixRevealClass"
+          aria-hidden="true"
+        >
+          <slot name="suffix" :direction="direction ?? null">
+            <span class="block size-3.5" :class="defaultArrowClass" />
+          </slot>
+        </span>
+      </button>
+    </Tooltip>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref, useTemplateRef } from 'vue'
+import { Tooltip } from '../../components/Tooltip'
+import type { ListHeaderCellSortProps } from './types'
+
+const props = defineProps<ListHeaderCellSortProps>()
+
+const emit = defineEmits<{
+  /** Fired on sort button click — update your sort state here. */
+  (e: 'click', event: MouseEvent): void
+}>()
+
+const isEnd = computed(() => props.align === 'end')
+
+// An inactive column's sort glyph is hidden until hover — but with opacity, not
+// display, so revealing it never shifts the label's position.
+const suffixRevealClass = computed(() =>
+  props.direction ? '' : 'opacity-0 group-hover:opacity-100',
+)
+
+// Built-in sort glyph, used when the consumer supplies no #suffix: a muted
+// up/down when inactive, a directional arrow when the column is the sort key.
+const defaultArrowClass = computed(() => {
+  if (!props.direction) return 'lucide-arrow-up-down'
+  return props.direction === 'asc' ? 'lucide-arrow-up' : 'lucide-arrow-down'
+})
+
+defineSlots<{
+  /** Column label. */
+  default?: () => unknown
+  /** Leading adornment, rendered before the label. */
+  prefix?: (props: { direction: 'asc' | 'desc' | null }) => unknown
+  /**
+   * Sort glyph. Optional — the cell renders a built-in arrow from `direction`
+   * by default. Provide this to override (e.g. a custom lucide span). The cell
+   * owns the reveal: an inactive column's glyph shows on hover.
+   */
+  suffix?: (props: { direction: 'asc' | 'desc' | null }) => unknown
+}>()
+
+// The label is slot content, so the tooltip reads the rendered text.
+const buttonEl = useTemplateRef('button')
+const label = ref('')
+onMounted(() => {
+  label.value = buttonEl.value?.textContent?.trim() ?? ''
+})
+const tooltipText = computed(() =>
+  label.value ? `Order by ${label.value.toLowerCase()}` : undefined,
+)
+</script>

package/src/molecules/list/ListRow.vue

@@ -0,0 +1,55 @@
+<template>
+  <!-- `custom` so this row's single click handler decides between toggle and
+       navigate — with RouterLink's own handler in play, selection could not
+       reliably preventDefault before it navigates. -->
+  <RouterLink v-if="to" :to="to" custom v-slot="{ href, navigate }">
+    <ListRowBase
+      tag="a"
+      :href="href"
+      :value="value"
+      @click="onClick($event, navigate)"
+    >
+      <slot />
+    </ListRowBase>
+  </RouterLink>
+  <ListRowBase
+    v-else
+    :tag="isInteractive() ? 'button' : 'div'"
+    :value="value"
+    @click="onClick"
+  >
+    <slot />
+  </ListRowBase>
+</template>
+
+<script setup lang="ts">
+import { RouterLink } from 'vue-router'
+import { useListContext } from './list-context'
+import ListRowBase from './ListRowBase.vue'
+import type { ListRowProps } from './types'
+
+const props = defineProps<ListRowProps>()
+
+const context = useListContext()
+
+// A row is interactive — rendered as a button — when it has a click handler or
+// when the list tracks an active row (clicking it sets active).
+function isInteractive() {
+  return Boolean(props.onClick) || Boolean(context?.activatable.value)
+}
+
+function onClick(event: MouseEvent, navigate?: (e?: MouseEvent) => void) {
+  if (context?.selectable.value && props.value !== undefined) {
+    event.preventDefault()
+    context.toggleSelection(props.value)
+    return
+  }
+  // Activation is additive: it sets the active row but still lets the app's own
+  // click handler / navigation run.
+  if (context?.activatable.value && props.value !== undefined) {
+    context.activate(props.value)
+  }
+  props.onClick?.(event)
+  navigate?.(event)
+}
+</script>

package/src/molecules/list/ListRowBase.vue

@@ -0,0 +1,103 @@
+<template>
+  <NativeElement
+    :tag="tag"
+    data-slot="list-row"
+    :role="context?.hasHeader.value ? 'row' : 'listitem'"
+    :data-interactive="interactive || undefined"
+    :data-state="selected ? 'selected' : undefined"
+    :data-active="active || undefined"
+    :aria-current="active || undefined"
+    :type="tag === 'button' ? 'button' : undefined"
+    :class="[
+      interactive && 'cursor-pointer select-none sm:rounded-[10px]',
+      // Active is a persistent, stronger surface; suppress the hover/active
+      // wash on it so pointing at the open row doesn't read as de-selecting it.
+      active
+        ? 'bg-surface-gray-3'
+        : interactive && 'active:bg-surface-gray-2 sm:hover:bg-surface-gray-1',
+    ]"
+  >
+    <slot />
+    <Transition
+      enter-active-class="transition-transform duration-75 ease-out"
+      leave-active-class="transition-transform duration-75 ease-out"
+      enter-from-class="scale-0"
+      leave-to-class="scale-0"
+    >
+      <div
+        v-if="selectable"
+        data-slot="list-row-checkbox"
+        role="checkbox"
+        :aria-checked="selected"
+        tabindex="0"
+        @click.stop.prevent="toggle"
+        @keydown.enter.prevent="toggle"
+        @keydown.space.prevent="toggle"
+      >
+        <!-- Purely presentational: the wrapper div is the real role=checkbox
+             control. pointer-events-none makes every click (even one landing
+             exactly on the native input) resolve to the wrapper's toggle,
+             instead of the raw input's native toggle fighting the one-way
+             :modelValue binding and netting to no change. -->
+        <Checkbox
+          :modelValue="selected"
+          tabindex="-1"
+          aria-hidden="true"
+          class="pointer-events-none"
+        />
+      </div>
+    </Transition>
+    <div
+      v-if="divider !== 'none'"
+      data-slot="list-divider"
+      aria-hidden="true"
+      class="border-t border-outline-gray-1 transition-opacity"
+      :style="{ gridColumn: divider === 'inset' ? '2 / -1' : '1 / -1' }"
+    />
+  </NativeElement>
+</template>
+
+<script setup lang="ts">
+import { computed, defineComponent, h } from 'vue'
+import Checkbox from '../../components/Checkbox/Checkbox.vue'
+import { useListContext } from './list-context'
+
+// `<component :is="'button'">` resolves the string through the consumer app's
+// component registry (capitalized to 'Button'), so an app that globally
+// registers a Button component hijacks the row element. h() with a tag string
+// always creates the native element and never consults the registry.
+const NativeElement = defineComponent({
+  props: { tag: { type: String, required: true } },
+  setup(props, { slots }) {
+    return () => h(props.tag, null, slots.default?.())
+  },
+})
+
+const props = defineProps<{
+  tag: 'a' | 'button' | 'div'
+  value?: string
+}>()
+
+const context = useListContext()
+
+const divider = computed(() => context?.divider.value ?? 'inset')
+const selectable = computed(
+  () => !!context?.selectable.value && props.value !== undefined,
+)
+const selected = computed(
+  () => selectable.value && !!context?.isSelected(props.value!),
+)
+const active = computed(
+  () =>
+    !!context?.activatable.value &&
+    props.value !== undefined &&
+    !!context?.isActive(props.value),
+)
+const interactive = computed(
+  () => props.tag !== 'div' || selectable.value || active.value,
+)
+
+function toggle() {
+  if (props.value !== undefined) context?.toggleSelection(props.value)
+}
+</script>

package/src/molecules/list/ListRows.vue

@@ -0,0 +1,120 @@
+<template>
+  <template v-if="!virtualEnabled">
+    <template v-for="(item, index) in items" :key="getItemValue(item, index)">
+      <slot :item="item" :index="index" :value="getItemValue(item, index)" />
+    </template>
+  </template>
+  <div v-else ref="anchor" v-bind="wrapperProps" role="presentation">
+    <template v-for="row in rows" :key="getItemValue(row.data, row.index)">
+      <slot
+        :item="row.data"
+        :index="row.index"
+        :value="getItemValue(row.data, row.index)"
+      />
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts" generic="T">
+import { computed, onBeforeUnmount, watch } from 'vue'
+import { useListContext } from './list-context'
+import { useVirtualRows } from './useVirtualRows'
+import type { ListVirtualOptions } from './types'
+
+const props = defineProps<{
+  /** Items to iterate — one default-slot render per item. */
+  items: T[]
+
+  /**
+   * How to derive a row's identity. A string reads that property off the item;
+   * a function computes it. Drives the render `:key`, the header select-all
+   * universe, and the scoped `value` slot prop. Defaults to the item's `name`,
+   * then `id`, then the index.
+   */
+  rowKey?: string | ((item: T, index: number) => PropertyKey)
+
+  /**
+   * Window the rows (vueuse useVirtualList) so only rows near the viewport
+   * mount. `itemHeight` defaults to the List's `rowHeight`; the scroll
+   * container is the nearest scrollable ancestor.
+   */
+  virtual?: boolean | ListVirtualOptions
+}>()
+
+defineSlots<{
+  default?: (props: { item: T; index: number; value: string }) => unknown
+}>()
+
+const context = useListContext()
+
+const itemHeight = computed(() => {
+  const fromOptions =
+    typeof props.virtual === 'object' ? props.virtual.itemHeight : undefined
+  return fromOptions ?? context?.rowHeight.value
+})
+
+const virtualEnabled = computed(() => {
+  if (!props.virtual) return false
+  if (!itemHeight.value) {
+    console.warn(
+      '[frappe-ui] <ListRows virtual> needs a row height — set `rowHeight` on <List> or pass `virtual.itemHeight`.',
+    )
+    return false
+  }
+  return true
+})
+
+const { rows, wrapperProps, anchor } = useVirtualRows(
+  () => (virtualEnabled.value ? props.items : []),
+  {
+    enabled: () => virtualEnabled.value,
+    itemHeight: () => itemHeight.value ?? 0,
+    overscan:
+      typeof props.virtual === 'object' ? props.virtual.overscan : undefined,
+  },
+)
+
+// Feed the full selectable universe to the List so the header select-all knows
+// every row's value — even the virtualized ones that aren't mounted. Uses the
+// same `getItemValue` as the render `:key` and scoped `value` slot prop, so
+// row identity has one source.
+watch(
+  () => props.items,
+  (items) => {
+    context?.setAllValues(items.map((item, i) => getItemValue(item, i)))
+  },
+  { immediate: true },
+)
+onBeforeUnmount(() => context?.setAllValues([]))
+
+function getItemValue(item: T, index: number) {
+  return String(getItemKey(item, index))
+}
+
+function getItemKey(item: T, index: number): PropertyKey {
+  if (props.rowKey !== undefined) {
+    const key =
+      typeof props.rowKey === 'function'
+        ? props.rowKey(item, index)
+        : isRecord(item)
+          ? (item as Record<string, unknown>)[props.rowKey]
+          : undefined
+    return isPropertyKey(key) ? key : index
+  }
+  if (!isRecord(item)) return index
+  const key = item.name ?? item.id
+  return isPropertyKey(key) ? key : index
+}
+
+function isRecord(value: unknown): value is { id?: unknown; name?: unknown } {
+  return value !== null && typeof value === 'object'
+}
+
+function isPropertyKey(value: unknown): value is PropertyKey {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'symbol'
+  )
+}
+</script>

package/src/molecules/list/index.ts

@@ -0,0 +1,24 @@
+// Structural styles ship with the package: importing from `frappe-ui/list`
+// pulls in the grid/divider rules so the family is self-contained.
+import './style.css'
+
+export { default as List } from './List.vue'
+export { default as ListRow } from './ListRow.vue'
+export { default as ListCell } from './ListCell.vue'
+export { default as ListHeader } from './ListHeader.vue'
+export { default as ListHeaderCell } from './ListHeaderCell.vue'
+export { default as ListHeaderCellSort } from './ListHeaderCellSort.vue'
+export { default as ListRows } from './ListRows.vue'
+export { default as ListGroup } from './ListGroup.vue'
+
+// The windowing composable behind <ListRows virtual>, for exotic cases.
+export { useVirtualRows, type UseVirtualRowsOptions } from './useVirtualRows'
+
+export type {
+  ListProps,
+  ListRowProps,
+  ListHeaderCellSortProps,
+  ListVirtualOptions,
+  ListDivider,
+  ListSortDirection,
+} from './types'