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

package/src/molecules/list/list-context.ts

@@ -0,0 +1,44 @@
+import { inject, provide, type ComputedRef, type InjectionKey, type Ref } from 'vue'
+import type { ListDivider } from './types'
+
+// Everything a List provides to its descendants. Internal — the public
+// contract is the components' props/models and the CSS hooks
+// (`--list-columns`, `--list-gap`, data-slot/data-state attributes).
+export interface ListContext {
+  divider: ComputedRef<ListDivider>
+  selectable: ComputedRef<boolean>
+  rowHeight: ComputedRef<number | undefined>
+
+  // Header presence drives ARIA roles: list/listitem without a header,
+  // table/row/columnheader/cell with one.
+  hasHeader: Ref<boolean>
+
+  isSelected: (value: string) => boolean
+  toggleSelection: (value: string) => void
+
+  // Header select-all. <ListRows> feeds the full selectable universe via
+  // `setAllValues` — it holds the complete `items` array even when the rows are
+  // virtualized, so the header checkbox can reflect/toggle "all" without every
+  // row being mounted. `selectAllState` drives the header checkbox's
+  // checked/indeterminate/empty rendering.
+  setAllValues: (values: string[]) => void
+  selectAllState: ComputedRef<'none' | 'some' | 'all'>
+  toggleSelectAll: () => void
+
+  // Single "active" row (v-model:active) — the one currently open/highlighted,
+  // separate from the checkbox `selection` set. `activatable` is true only when
+  // the List actually binds v-model:active, so plain navigation lists opt out.
+  activatable: ComputedRef<boolean>
+  isActive: (value: string) => boolean
+  activate: (value: string) => void
+}
+
+const listContextKey: InjectionKey<ListContext> = Symbol('frappe-ui:list')
+
+export function provideListContext(context: ListContext) {
+  provide(listContextKey, context)
+}
+
+export function useListContext() {
+  return inject(listContextKey, null)
+}

package/src/molecules/list/list.api.md

@@ -0,0 +1,276 @@
+<!-- Auto Generated by scripts/propsgen.ts -->
+<script setup>
+  import PropsTable from '@/components/Docs/PropsTable.vue'
+  import SlotsTable from '@/components/Docs/SlotsTable.vue'
+  import EmitsTable from '@/components/Docs/EmitsTable.vue'
+
+  const listProps = [
+  {
+    name: 'columns',
+    description: 'Grid track sizes, written to the `--list-columns` CSS var shared by the\nheader and every row. Defaults to the feed template\n`[\'auto\', \'minmax(0,1fr)\', \'auto\']` (leading media, content, trailing).\nTable-style lists must pass deterministic track sizes — `auto` tracks\nsize independently per row.',
+    required: false,
+    type: 'string[]'
+  },
+  {
+    name: 'divider',
+    description: 'Divider treatment between rows: `inset` starts at the content column\n(the text edge), `full` spans all columns. Defaults to `inset` with the\ndefault feed template, `full` when `columns` is set.',
+    required: false,
+    type: 'ListDivider'
+  },
+  {
+    name: 'selectable',
+    description: 'Reveals the animated checkbox column and switches row click from\nnavigate to toggle. Selected values surface via `v-model:selection`.',
+    required: false,
+    type: 'boolean'
+  },
+  {
+    name: 'rowHeight',
+    description: 'Fixed row height in px (sets `--list-row-height`). Required for\nvirtualization; without it rows size to their content. Responsive\nheights are non-virtual — set them with classes on the rows instead.',
+    required: false,
+    type: 'number'
+  },
+  {
+    name: 'selection',
+    description: '',
+    required: false,
+    type: 'string[]',
+    default: '[]'
+  },
+  {
+    name: 'active',
+    description: '',
+    required: false,
+    type: 'string'
+  }
+]
+
+  const listSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const listEmits = [
+  {
+    name: 'update:selection',
+    description: 'Fired when the selection changes.',
+    type: '[value: string[]]'
+  },
+  {
+    name: 'update:active',
+    description: 'Fired when the active changes.',
+    type: '[value: string | undefined]'
+  }
+]
+
+  const listRowProps = [
+  {
+    name: 'to',
+    description: 'Renders the row as a RouterLink. Without `to`, a row with a click\nlistener renders as a button; otherwise a plain div.',
+    required: false,
+    type: 'string | kt | Tt'
+  },
+  {
+    name: 'value',
+    description: 'Row key — the `selection` key when `selectable` and the `v-model:active`\nkey. Required whenever the list uses either.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'onClick',
+    description: 'Fired when the row is activated, unless selection mode claims the click.',
+    required: false,
+    type: '((event: MouseEvent) => void)'
+  }
+]
+
+  const listRowSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const listCellSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const listHeaderSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const listHeaderCellSlots = [
+  {
+    name: 'default',
+    description: 'Column label.',
+    type: 'any'
+  },
+  {
+    name: 'prefix',
+    description: 'Leading adornment, rendered before the label.',
+    type: 'any'
+  },
+  {
+    name: 'suffix',
+    description: 'Trailing adornment, rendered after the label.',
+    type: 'any'
+  }
+]
+
+  const listHeaderCellSortProps = [
+  {
+    name: 'direction',
+    description: 'Active sort direction for this column, `null`/omitted when inactive.\nThe cell is controlled — sort state and toggle rules are app-owned:\nupdate whatever drives your ordering in the `click` handler.',
+    required: false,
+    type: 'ListSortDirection | null'
+  },
+  {
+    name: 'align',
+    description: 'Horizontal alignment of the header content. `\'end\'` right-aligns the cell\n(for numeric/right-aligned columns) *and* moves the sort glyph to the\nleading side, so the label stays flush with the column\'s right edge and\nlines up with the values below. Defaults to `\'start\'`.',
+    required: false,
+    type: '"start" | "end"'
+  }
+]
+
+  const listHeaderCellSortSlots = [
+  {
+    name: 'default',
+    description: 'Column label.',
+    type: 'any'
+  },
+  {
+    name: 'prefix',
+    description: 'Leading adornment, rendered before the label.',
+    type: '{ direction: "desc" | "asc" | null; }'
+  },
+  {
+    name: 'suffix',
+    description: 'Sort glyph. Optional — the cell renders a built-in arrow from `direction`\nby default. Provide this to override (e.g. a custom lucide span). The cell\nowns the reveal: an inactive column\'s glyph shows on hover.',
+    type: '{ direction: "desc" | "asc" | null; }'
+  }
+]
+
+  const listHeaderCellSortEmits = [
+  {
+    name: 'click',
+    description: '',
+    type: '[event: MouseEvent]'
+  }
+]
+
+  const listRowsProps = [
+  {
+    name: 'items',
+    description: 'Items to iterate — one default-slot render per item.',
+    required: true,
+    type: 'T[]'
+  },
+  {
+    name: 'rowKey',
+    description: 'How to derive a row\'s identity. A string reads that property off the item;\na function computes it. Drives the render `:key`, the header select-all\nuniverse, and the scoped `value` slot prop. Defaults to the item\'s `name`,\nthen `id`, then the index.',
+    required: false,
+    type: 'string | ((item: T, index: number) => PropertyKey)'
+  },
+  {
+    name: 'virtual',
+    description: 'Window the rows (vueuse useVirtualList) so only rows near the viewport\nmount. `itemHeight` defaults to the List\'s `rowHeight`; the scroll\ncontainer is the nearest scrollable ancestor.',
+    required: false,
+    type: 'boolean | ListVirtualOptions'
+  }
+]
+
+  const listRowsSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{ item: T; index: number; value: string; }'
+  }
+]
+
+  const listGroupProps = [
+  {
+    name: 'label',
+    description: 'Section label shown in the group header. Overridden by the #header slot.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'sticky',
+    description: 'Pin the group header to the top of the scroll container while its rows\nscroll under it. Off by default.',
+    required: false,
+    type: 'boolean'
+  }
+]
+
+  const listGroupSlots = [
+  {
+    name: 'default',
+    description: 'The group\'s rows — `<ListRow>` elements.',
+    type: 'any'
+  },
+  {
+    name: 'header',
+    description: 'Replaces the header content (the label).',
+    type: 'any'
+  }
+]
+</script>
+
+## API Reference
+
+### List
+
+<PropsTable folder="list" name="List" :data="listProps"/>
+
+<SlotsTable :data="listSlots"/>
+
+<EmitsTable :data="listEmits"/>
+
+### ListRow
+
+<PropsTable folder="list" name="ListRow" :data="listRowProps"/>
+
+<SlotsTable :data="listRowSlots"/>
+
+### ListCell
+
+<SlotsTable :data="listCellSlots"/>
+
+### ListHeader
+
+<SlotsTable :data="listHeaderSlots"/>
+
+### ListHeaderCell
+
+<SlotsTable :data="listHeaderCellSlots"/>
+
+### ListHeaderCellSort
+
+<PropsTable folder="list" name="ListHeaderCellSort" :data="listHeaderCellSortProps"/>
+
+<SlotsTable :data="listHeaderCellSortSlots"/>
+
+<EmitsTable :data="listHeaderCellSortEmits"/>
+
+### ListRows
+
+<PropsTable folder="list" name="ListRows" :data="listRowsProps"/>
+
+<SlotsTable :data="listRowsSlots"/>
+
+### ListGroup
+
+<PropsTable folder="list" name="ListGroup" :data="listGroupProps"/>
+
+<SlotsTable :data="listGroupSlots"/>

package/src/molecules/list/list.md

@@ -0,0 +1,119 @@
+# List
+
+Composition-based list primitives under the `frappe-ui/list` subpath. Every list
+surface is one column grid: a feed row is just the default column template, a
+table is an explicit one. The family owns geometry — columns, dividers, hover
+surfaces, selection and sort chrome — and nothing readable: cell contents
+(typography, avatars, badges, unread emphasis) are entirely app-authored.
+
+Not to be confused with the config-driven `ListView` in the main entry — that
+stays untouched; import from `frappe-ui/list` for this family.
+
+## Feed mode
+
+The default template (`auto`, `minmax(0,1fr)`, `auto`) fits leading media,
+content, and a right-aligned trailing cell. Rows with `to` render as
+RouterLinks, rows with a click listener as buttons. `selectable` reveals the
+animated checkbox column and switches row click from navigate to toggle;
+selected values surface through `v-model:selection`. When a `ListHeader` is
+present, a select-all checkbox appears in it automatically — checked when every
+row is selected, mixed when only some are, and toggling all rows on or off. It
+reasons over the full `ListRows` items, so it covers virtualized rows too.
+`ListRows` resolves each row's identity once and exposes it as the scoped
+`value` prop. The identity defaults to the item's `name`/`id`; pass `row-key` (a
+field name or `(item, index) => key`) when the row should use a different field.
+
+Dividers default to `inset`: they start at the content column (the text edge) by
+construction, never render above the first row, and hide around a hovered row so
+the rounded hover surface floats free.
+
+<ComponentPreview name="List-Feed" />
+
+## Active row
+
+A master–detail list (a mail inbox, a file browser) tracks one open row. Bind
+`v-model:active` to a row `value` and the List owns the rest: it highlights that
+row and hides the dividers hugging it — above and below — so its rounded surface
+floats free, like a hovered row but persistent. Clicking a row sets `active`;
+unlike `selectable`, activation is additive, so the row's own `@click` and `to`
+navigation still run. It's single-select and independent of the multi-select
+checkbox `selection` — and works in feed or column mode.
+
+```vue
+<List v-model:active="openId">
+  <ListRows :items="threads" v-slot="{ value }">
+    <ListRow :value="value">…</ListRow>
+  </ListRows>
+</List>
+```
+
+## Column mode
+
+Pass explicit `columns` (deterministic track sizes — `auto` tracks size
+independently per row) and a `ListHeader`. Header and rows share one
+`--list-columns` template, so they can never drift.
+
+`ListHeaderCell` is a plain label with optional `#prefix` / `#suffix`
+adornments. Sortable columns use `ListHeaderCellSort` instead — a controlled
+sort button: you hand it the active `direction` (`asc` / `desc` / `null`) and
+update your own sort state in its `click` handler. Your code owns the state,
+toggle rules, direction glyphs (via the scoped `#suffix="{ direction }"` slot),
+and whether ordering happens client-side or through `useList` orderBy. The cell
+keeps only the behavioral chrome: a real button, `aria-sort`, the tooltip, and
+revealing an inactive column's suffix on hover. Both variants render the same
+`data-slot="list-header-cell"` geometry, so mixing them in one header is
+seamless.
+
+<ComponentPreview name="List-Columns" />
+
+## Virtual rows
+
+`ListRows` iterates items through its scoped slot; with `virtual`, only rows
+near the viewport mount. The scoped slot receives `{ item, index, value }`,
+where `value` is the string row identity used by select-all and active-row
+state. The scroll container is the nearest scrollable ancestor — the list
+windows against an app-owned scroll area (a settings body, the page) and keeps
+its scrollbar. `itemHeight` defaults to the List's `rowHeight`. The underlying
+composable, `useVirtualRows`, is exported for exotic cases.
+
+<ComponentPreview name="List-Virtual" csr="true" />
+
+## Styling hooks
+
+`--list-columns` and `--list-gap` (default `0.5rem`) are public hooks on the
+List — override them with plain classes, responsively if needed. People-style
+lists collapse to a feed on mobile with no dedicated API:
+
+```vue
+<List
+  :columns="['minmax(8rem,1fr)', '5.5rem', '5.5rem']"
+  class="max-sm:[--list-columns:auto_minmax(0,1fr)_auto]"
+>
+```
+
+with `max-sm:hidden` on the numeric cells and the `ListHeader`.
+
+For `--list-gap` and `--list-row-padding-x` (the content inset shared by
+interactive rows — default `0.75rem` — and the column header, so setting it on
+the `List` aligns both), the frappe-ui Tailwind preset ships spacing-scale
+utilities — `list-gap-*` and `list-row-px-*` — so the usual authoring form is
+`max-sm:list-gap-3 sm:list-gap-4` rather than raw `[--list-gap:0.75rem]`
+properties. Both forms hit the same CSS vars.
+
+Cells (and plain header cells) are flex containers with `items-center` — align
+content with justify utilities (`class="justify-end"` for numeric columns),
+responsively if needed. For sortable numeric headers, use
+`<ListHeaderCellSort align="end">` so the sort glyph moves to the leading side
+and the label stays flush with the column edge.
+
+Slots for CSS targeting:
+`data-slot="list | list-header | list-header-cell | list-row | list-cell | list-row-checkbox | list-divider"`.
+State: `data-state="selected"` (checkbox selection), `data-active` (+
+`aria-current`, the `v-model:active` row) and `data-interactive` on rows,
+`data-sort` on the active header cell.
+
+Accessibility follows header presence: `role="list"` / `"listitem"` without a
+`ListHeader`, `table` / `row` / `columnheader` / `cell` (plus `aria-sort`) with
+one.
+
+<!-- @include: ./list.api.md -->

package/src/molecules/list/stories/Columns.vue

@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { Avatar, Button } from 'frappe-ui'
+import {
+  List,
+  ListRow,
+  ListCell,
+  ListHeader,
+  ListHeaderCell,
+  ListHeaderCellSort,
+  ListRows,
+} from 'frappe-ui/list'
+
+const members = [
+  { name: 'Rosa Diaz', email: 'rosa@example.com', role: 'Admin', since: '2021-06' },
+  { name: 'Jake Peralta', email: 'jake@example.com', role: 'Member', since: '2022-01' },
+  { name: 'Amy Santiago', email: 'amy@example.com', role: 'Admin', since: '2020-11' },
+  { name: 'Terry Jeffords', email: 'terry@example.com', role: 'Member', since: '2023-03' },
+  { name: 'Raymond Holt', email: 'holt@example.com', role: 'Guest', since: '2024-08' },
+]
+
+// Sort state, toggle rules, comparator, and direction icons are all app
+// code — the header cells only render the chrome for whatever `direction`
+// you hand them.
+type Field = 'name' | 'role' | 'since'
+
+function sortIcon(direction: 'asc' | 'desc' | null) {
+  if (!direction) return 'lucide-arrow-up-down'
+  return direction === 'asc' ? 'lucide-arrow-up' : 'lucide-arrow-down'
+}
+const sortField = ref<Field>('name')
+const sortDirection = ref<'asc' | 'desc'>('asc')
+
+function toggleSort(field: Field, firstDirection: 'asc' | 'desc' = 'asc') {
+  if (sortField.value === field) {
+    sortDirection.value = sortDirection.value === 'asc' ? 'desc' : 'asc'
+  } else {
+    sortField.value = field
+    sortDirection.value = firstDirection
+  }
+}
+
+function directionFor(field: Field) {
+  return sortField.value === field ? sortDirection.value : null
+}
+
+const sortedMembers = computed(() => {
+  const factor = sortDirection.value === 'desc' ? -1 : 1
+  return [...members].sort(
+    (a, b) => factor * a[sortField.value].localeCompare(b[sortField.value]),
+  )
+})
+</script>
+
+<template>
+  <List class="w-full" :columns="['minmax(0,1fr)', '7rem', '8rem', '3rem']" :row-height="56">
+    <ListHeader>
+      <ListHeaderCellSort :direction="directionFor('name')" @click="toggleSort('name')">
+        Member
+        <template #suffix="{ direction }">
+          <span class="block size-3.5" :class="sortIcon(direction)" />
+        </template>
+      </ListHeaderCellSort>
+      <ListHeaderCellSort :direction="directionFor('role')" @click="toggleSort('role')">
+        Role
+        <template #suffix="{ direction }">
+          <span class="block size-3.5" :class="sortIcon(direction)" />
+        </template>
+      </ListHeaderCellSort>
+      <ListHeaderCellSort
+        :direction="directionFor('since')"
+        class="justify-end"
+        @click="toggleSort('since', 'desc')"
+      >
+        Member since
+        <template #suffix="{ direction }">
+          <span class="block size-3.5" :class="sortIcon(direction)" />
+        </template>
+      </ListHeaderCellSort>
+      <ListHeaderCell />
+    </ListHeader>
+    <ListRows :items="sortedMembers" v-slot="{ item: member }">
+      <ListRow>
+        <ListCell>
+          <Avatar :label="member.name" size="xl" />
+          <div class="ml-3 min-w-0">
+            <div class="truncate text-base text-ink-gray-8">{{ member.name }}</div>
+            <div class="mt-0.5 truncate text-sm text-ink-gray-5">{{ member.email }}</div>
+          </div>
+        </ListCell>
+        <ListCell>
+          <span class="text-base text-ink-gray-7">{{ member.role }}</span>
+        </ListCell>
+        <ListCell class="justify-end">
+          <span class="text-base text-ink-gray-6">{{ member.since }}</span>
+        </ListCell>
+        <ListCell class="justify-end">
+          <Button variant="ghost" icon="lucide-trash-2" label="Remove member" />
+        </ListCell>
+      </ListRow>
+    </ListRows>
+  </List>
+</template>

package/src/molecules/list/stories/Feed.vue

@@ -0,0 +1,105 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Avatar, Badge, Button } from 'frappe-ui'
+import { List, ListRow, ListCell } from 'frappe-ui/list'
+
+const discussions = [
+  {
+    name: '1',
+    title: 'Weekly sync notes',
+    author: 'Rosa Diaz',
+    comment: 'Sounds good, let us ship it on Monday',
+    time: '2 h',
+    comments: 4,
+    unread: true,
+  },
+  {
+    name: '2',
+    title: 'Redesigning the onboarding flow',
+    author: 'Jake Peralta',
+    comment: 'I added the new mockups to the page',
+    time: '5 h',
+    comments: 12,
+    unread: false,
+  },
+  {
+    name: '3',
+    title: 'Q3 hiring plan',
+    author: 'Amy Santiago',
+    comment: 'Two backend roles and one designer',
+    time: '1 d',
+    comments: 7,
+    unread: true,
+  },
+  {
+    name: '4',
+    title: 'Incident review: search downtime',
+    author: 'Terry Jeffords',
+    comment: 'Root cause was the index rebuild',
+    time: '2 d',
+    comments: 9,
+    unread: false,
+  },
+  {
+    name: '5',
+    title: 'Docs sprint retrospective',
+    author: 'Raymond Holt',
+    comment: 'Velocity was acceptable.',
+    time: '4 d',
+    comments: 3,
+    unread: false,
+  },
+]
+
+const selectable = ref(false)
+const selection = ref<string[]>([])
+
+function toggleSelectMode() {
+  selectable.value = !selectable.value
+  selection.value = []
+}
+</script>
+
+<template>
+  <div class="w-full">
+    <div class="mb-2 flex h-7 items-center justify-end gap-3">
+      <span v-if="selection.length" class="text-sm text-ink-gray-5">
+        {{ selection.length }} selected
+      </span>
+      <Button @click="toggleSelectMode">
+        {{ selectable ? 'Done' : 'Select' }}
+      </Button>
+    </div>
+    <List :selectable="selectable" v-model:selection="selection" :row-height="60">
+      <ListRow
+        v-for="discussion in discussions"
+        :key="discussion.name"
+        :value="discussion.name"
+        @click="() => {}"
+      >
+        <ListCell>
+          <Avatar :label="discussion.author" size="2xl" />
+        </ListCell>
+        <ListCell>
+          <div class="min-w-0">
+            <div
+              class="truncate text-base text-ink-gray-8"
+              :class="discussion.unread && 'font-semibold'"
+            >
+              {{ discussion.title }}
+            </div>
+            <div class="mt-1 truncate text-base text-ink-gray-5">
+              {{ discussion.author }}: {{ discussion.comment }}
+            </div>
+          </div>
+        </ListCell>
+        <ListCell class="justify-end">
+          <div class="flex flex-col items-end gap-1">
+            <span class="text-sm text-ink-gray-5">{{ discussion.time }}</span>
+            <Badge>{{ discussion.comments }}</Badge>
+          </div>
+        </ListCell>
+      </ListRow>
+    </List>
+  </div>
+</template>

package/src/molecules/list/stories/Virtual.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { List, ListRow, ListCell, ListRows } from 'frappe-ui/list'
+
+const items = Array.from({ length: 1000 }, (_, i) => ({
+  id: String(i + 1),
+  title: `Task ${i + 1}`,
+  status: i % 3 === 0 ? 'Done' : i % 3 === 1 ? 'In progress' : 'Backlog',
+}))
+</script>
+
+<template>
+  <!-- The scroll container is app-owned: ListRows finds the nearest
+       scrollable ancestor and windows against it. -->
+  <div class="h-72 w-full overflow-y-auto rounded border">
+    <List :columns="['3rem', 'minmax(0,1fr)', '6rem']" :row-height="44" class="px-2">
+      <ListRows :items="items" virtual v-slot="{ item }">
+        <ListRow>
+          <ListCell>
+            <span class="text-sm text-ink-gray-4">#{{ item.id }}</span>
+          </ListCell>
+          <ListCell>
+            <span class="truncate text-base text-ink-gray-8">{{ item.title }}</span>
+          </ListCell>
+          <ListCell class="justify-end">
+            <span class="text-sm text-ink-gray-5">{{ item.status }}</span>
+          </ListCell>
+        </ListRow>
+      </ListRows>
+    </List>
+  </div>
+</template>