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

package/src/molecules/list/style.css

@@ -0,0 +1,173 @@
+/* Structural rules for the list family. Geometry only — colors and type live
+ * in the components as semantic-token classes.
+ *
+ * `--list-columns` and `--list-gap` are public styling hooks: apps override
+ * them with plain (responsive) classes on <List>. Every rule that sets a
+ * hook default is wrapped in :where() so any consumer class wins on
+ * specificity, regardless of stylesheet order. */
+
+:where([data-slot='list']) {
+  /* --list-columns-default carries the `columns` prop (inline style on the
+   * List). The indirection keeps --list-columns itself free for class
+   * overrides like `max-sm:list-cols-[auto_minmax(0,1fr)_auto]` (the
+   * tailwind preset's sugar over the var). */
+  --list-columns: var(--list-columns-default, auto minmax(0, 1fr) auto);
+}
+
+/* Attribute (not :where) specificity, so element-level resets — Tailwind
+ * preflight's `button { padding: 0 }` for button rows — don't beat the
+ * padding below. `text-align: start` undoes the UA button centering. */
+[data-slot='list-row'],
+[data-slot='list-header'] {
+  display: grid;
+  grid-template-columns: var(--list-columns);
+  column-gap: var(--list-gap, 0.5rem);
+  align-items: center;
+  text-align: start;
+}
+
+/* The checkbox column is not a grid track (a 0px track would still get a
+ * column gap next to it). It's start padding — 0px or 32px, set by the
+ * List — so grid line numbers never shift and the reveal is one animated
+ * padding. The checkbox itself is an overlay in the padding area. */
+[data-slot='list-row'] {
+  padding-inline-start: calc(
+    var(--list-checkbox-width, 0px) + var(--_list-row-pad, 0px)
+  );
+  padding-inline-end: var(--_list-row-pad, 0px);
+}
+
+/* The header inset comes from the *public* --list-row-padding-x hook (not the
+ * private --_list-row-pad, which is only ever set on interactive rows and so
+ * left the header flush-left beside padded rows). Defaults to 0 — the neutral
+ * flush edge — because a header can't tell whether its rows are interactive
+ * (0.75rem inset) or static (flush): the consumer declares the inset once on
+ * the List, e.g. `list-row-px-3`, and it flows to both header and rows so they
+ * can't drift. In :where() (zero specificity) so that class wins — and unlike a
+ * raw `px-3`, the hook composes with the checkbox column instead of clobbering
+ * the padding-inline-start calc below. */
+:where([data-slot='list-header']) {
+  padding-inline-start: calc(
+    var(--list-checkbox-width, 0px) + var(--list-row-padding-x, 0px)
+  );
+  padding-inline-end: var(--list-row-padding-x, 0px);
+}
+
+/* Group header aligns its label with the rows' content: same checkbox-column +
+ * row inset as the header/rows, so a section title sits directly above the text
+ * it groups. In :where() so consumer classes win. */
+:where([data-slot='list-group-header']) {
+  padding-inline-start: calc(
+    var(--list-checkbox-width, 0px) + var(--list-row-padding-x, 0px)
+  );
+  padding-inline-end: var(--list-row-padding-x, 0px);
+}
+
+/* Positioned so dividers/checkbox overlays anchor to the row. In :where()
+ * (unlike the block above, which needs attribute specificity only to beat
+ * preflight's button resets) so a consumer `sticky` class wins — e.g. a
+ * header pinned inside its scroll container. */
+:where([data-slot='list-row'], [data-slot='list-header']) {
+  position: relative;
+}
+
+:where([data-slot='list-row']) {
+  height: var(--list-row-height, auto);
+  /* padding animates the checkbox-column reveal; background-color fades the
+   * hover surface (a transition-colors class here would clobber the padding
+   * transition, so both live in one declaration). */
+  transition:
+    padding 200ms ease-out,
+    background-color 150ms;
+}
+
+/* Interactive rows get the rounded hover surface, so their content needs an
+ * inset from the surface edge. Override via --list-row-padding-x. Width lives
+ * here (not as a class) so a consumer class can narrow a row — e.g. to leave
+ * room for an action button beside it. */
+:where([data-slot='list-row'][data-interactive]) {
+  --_list-row-pad: var(--list-row-padding-x, 0.75rem);
+  width: 100%;
+}
+
+:where([data-slot='list-row-checkbox'], [data-slot='list-header-checkbox']) {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  /* Row checkboxes sit inside the interactive row's hover inset; the header
+   * has no such inset, so it anchors to its own content padding instead. Both
+   * land the 32px checkbox column in the same place so they align vertically. */
+  inset-inline-start: var(--_list-row-pad, 0px);
+  display: flex;
+  align-items: center;
+  width: 32px;
+  overflow: hidden;
+}
+
+:where([data-slot='list-header-checkbox']) {
+  inset-inline-start: var(--list-row-padding-x, 0px);
+}
+
+/* The header's bottom border is a grid child spanning all tracks, so it
+ * aligns with the rows' content (and their full-width dividers) whatever
+ * padding the header carries — a border on the header box itself would run
+ * through the padding and overshoot the dividers on both sides. */
+:where([data-slot='list-header-border']) {
+  position: absolute;
+  /* grid-row stays auto so bottom: 0 is the header's own bottom edge (see
+   * the list-divider rule below), while grid-column tracks the columns. */
+  grid-column: 1 / -1;
+  bottom: 0;
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+  height: 0;
+  pointer-events: none;
+}
+
+/* Dividers are absolutely-positioned grid children: their grid-column
+ * placement (inset `2 / -1`, full `1 / -1` — set by ListRow) resolves
+ * against the shared template, so the inset divider starts at the content
+ * column's own edge with no magic offsets, without occupying cells that
+ * would derail the cells' auto-placement. */
+:where([data-slot='list-divider']) {
+  position: absolute;
+  /* grid-row stays auto: per spec an abs-positioned grid child with auto
+   * placement in an axis anchors to the padding box in that axis, so top: 0
+   * is the row's own top edge. Anchoring to grid-row 1 would put the divider
+   * below the row's padding-top, displacing it into padded rows. */
+  top: 0;
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+  height: 0;
+  pointer-events: none;
+}
+
+/* Between-ness is pure CSS: only a row following another row shows its
+ * divider-above. The first row never shows one, trailing non-row content
+ * (e.g. a "Load more" button) doesn't break it, and it keeps working inside
+ * the virtualizer wrapper because windowed rows stay siblings. */
+[data-slot='list-row'] [data-slot='list-divider'] {
+  opacity: 0;
+}
+[data-slot='list-row'] + [data-slot='list-row'] [data-slot='list-divider'] {
+  opacity: 1;
+}
+
+/* Hover hides both edges of the hovered row so the rounded hover surface
+ * floats free. Gated on data-interactive so static rows keep dividers. */
+[data-slot='list-row'][data-interactive]:hover [data-slot='list-divider'],
+[data-slot='list-row'][data-interactive]:hover
+  + [data-slot='list-row']
+  [data-slot='list-divider'] {
+  opacity: 0;
+}
+
+/* The active row (v-model:active) is a persistent version of the same idea:
+ * its rounded highlight surface floats free of the rules above and below it.
+ * Hides its own divider-above and the next row's (the divider below it). */
+[data-slot='list-row'][data-active] [data-slot='list-divider'],
+[data-slot='list-row'][data-active]
+  + [data-slot='list-row']
+  [data-slot='list-divider'] {
+  opacity: 0;
+}

package/src/molecules/list/types.ts

@@ -0,0 +1,82 @@
+import type { RouteLocationRaw } from 'vue-router'
+
+export type ListDivider = 'inset' | 'full' | 'none'
+export type ListSortDirection = 'asc' | 'desc'
+
+export interface ListProps {
+  /**
+   * Grid track sizes, written to the `--list-columns` CSS var shared by the
+   * header and every row. Defaults to the feed template
+   * `['auto', 'minmax(0,1fr)', 'auto']` (leading media, content, trailing).
+   * Table-style lists must pass deterministic track sizes — `auto` tracks
+   * size independently per row.
+   */
+  columns?: string[]
+
+  /**
+   * Divider treatment between rows: `inset` starts at the content column
+   * (the text edge), `full` spans all columns. Defaults to `inset` with the
+   * default feed template, `full` when `columns` is set.
+   */
+  divider?: ListDivider
+
+  /**
+   * Reveals the animated checkbox column and switches row click from
+   * navigate to toggle. Selected values surface via `v-model:selection`.
+   */
+  selectable?: boolean
+
+  // Two more models live on List but aren't plain props (so they're not in
+  // this interface): `v-model:selection` (string[], the checkbox set) and
+  // `v-model:active` (string, the single open/highlighted row — the List
+  // styles it and hides the dividers hugging it). See List.vue.
+
+  /**
+   * Fixed row height in px (sets `--list-row-height`). Required for
+   * virtualization; without it rows size to their content. Responsive
+   * heights are non-virtual — set them with classes on the rows instead.
+   */
+  rowHeight?: number
+}
+
+export interface ListRowProps {
+  /**
+   * Renders the row as a RouterLink. Without `to`, a row with a click
+   * listener renders as a button; otherwise a plain div.
+   */
+  to?: RouteLocationRaw
+
+  /**
+   * Row key — the `selection` key when `selectable` and the `v-model:active`
+   * key. Required whenever the list uses either.
+   */
+  value?: string
+
+  /** Fired when the row is activated, unless selection mode claims the click. */
+  onClick?: (event: MouseEvent) => void
+}
+
+export interface ListHeaderCellSortProps {
+  /**
+   * Active sort direction for this column, `null`/omitted when inactive.
+   * The cell is controlled — sort state and toggle rules are app-owned:
+   * update whatever drives your ordering in the `click` handler.
+   */
+  direction?: ListSortDirection | null
+
+  /**
+   * Horizontal alignment of the header content. `'end'` right-aligns the cell
+   * (for numeric/right-aligned columns) *and* moves the sort glyph to the
+   * leading side, so the label stays flush with the column's right edge and
+   * lines up with the values below. Defaults to `'start'`.
+   */
+  align?: 'start' | 'end'
+}
+
+export interface ListVirtualOptions {
+  /** Row height in px. Defaults to the List's `rowHeight`. */
+  itemHeight?: number
+
+  /** Rows rendered beyond the visible window on each side. */
+  overscan?: number
+}

package/src/molecules/list/useVirtualRows.ts

@@ -0,0 +1,80 @@
+import {
+  computed,
+  ref,
+  toValue,
+  watchEffect,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import { useEventListener, useVirtualList } from '@vueuse/core'
+
+export interface UseVirtualRowsOptions {
+  /** Enables DOM scroll-container lookup and scroll listener registration. */
+  enabled?: MaybeRefOrGetter<boolean>
+
+  /** Row height in px. */
+  itemHeight: MaybeRefOrGetter<number>
+
+  /** Rows rendered beyond the visible window on each side. */
+  overscan?: number
+
+  /** Explicit scroll container. Defaults to the nearest scrollable ancestor of `anchor`. */
+  scrollContainer?: MaybeRefOrGetter<HTMLElement | null | undefined>
+}
+
+/**
+ * Windowing for list rows whose scroll container is an ancestor the app owns
+ * (a settings body, the page itself) rather than an element the virtualizer
+ * renders. Wraps vueuse's useVirtualList: points its container ref at the
+ * discovered ancestor and forwards that element's scroll events, so the
+ * app keeps its own scroll container and styled scrollbar.
+ *
+ * Bind `anchor` to the element wrapping the windowed rows (`wrapperProps`
+ * carries the height/offset styles vueuse computes for it).
+ */
+export function useVirtualRows<T>(
+  items: MaybeRefOrGetter<T[]>,
+  options: UseVirtualRowsOptions,
+) {
+  const source = computed(() => toValue(items))
+  const { list, containerProps, wrapperProps } = useVirtualList(
+    source as Ref<T[]>,
+    {
+      itemHeight: () => toValue(options.itemHeight),
+      overscan: options.overscan ?? 6,
+    },
+  )
+
+  const anchor = ref<HTMLElement | null>(null)
+  watchEffect(() => {
+    if (!toValue(options.enabled ?? true)) {
+      containerProps.ref.value = null
+      return
+    }
+    const explicit = toValue(options.scrollContainer)
+    containerProps.ref.value = explicit ?? findScrollContainer(anchor.value)
+  })
+  useEventListener(
+    () => (toValue(options.enabled ?? true) ? containerProps.ref.value : null),
+    'scroll',
+    () => containerProps.onScroll(),
+  )
+
+  return { rows: list, wrapperProps, anchor }
+}
+
+function findScrollContainer(el: HTMLElement | null): HTMLElement | null {
+  let node = el?.parentElement ?? null
+  while (node) {
+    const { overflowY } = getComputedStyle(node)
+    if (
+      overflowY === 'auto' ||
+      overflowY === 'scroll' ||
+      overflowY === 'overlay'
+    ) {
+      return node
+    }
+    node = node.parentElement
+  }
+  return null
+}

package/src/resources/documentResource.d.ts

@@ -0,0 +1,28 @@
+import type { Resource, ResourceOptions } from './resources'
+
+export interface DocumentResource<TDoc = any> {
+  doctype: string
+  name: string
+  doc: TDoc | null
+  originalDoc: TDoc | null
+  isDirty: boolean
+  auto: boolean
+  get: Resource<TDoc>
+  setValue: Resource<TDoc>
+  setValueDebounced: Resource<TDoc>
+  save: Resource<TDoc>
+  delete: Resource<TDoc>
+  reload: () => Promise<TDoc | null>
+  setDoc: (doc: TDoc | ((current: TDoc | null) => TDoc)) => void
+  [key: string]: any
+}
+
+export function createDocumentResource<TDoc = any>(
+  options: ResourceOptions & { doctype: string; name: string },
+  vm?: any,
+): DocumentResource<TDoc>
+
+export function getCachedDocumentResource<TDoc = any>(
+  doctype: string,
+  name: string,
+): DocumentResource<TDoc> | null

package/src/resources/documentResource.js

@@ -108,13 +108,10 @@ export function createDocumentResource(options, vm) {
       {
         ...setValueOptions,
         makeParams() {
-          let values = JSON.parse(JSON.stringify(out.doc))
-          delete values.doctype
-          delete values.name
           return {
             doctype: out.doctype,
             name: out.name,
-            fieldname: values,
+            fieldname: getChangedFields(),
           }
         },
       },
@@ -143,6 +140,18 @@ export function createDocumentResource(options, vm) {
     setDoc,
   })
 
+  // skip the network round-trip when save is called with no pending changes
+  const saveFetch = out.save.fetch
+  function saveIfChanged(...args) {
+    if (Object.keys(getChangedFields()).length === 0) {
+      return Promise.resolve(out.doc)
+    }
+    return saveFetch(...args)
+  }
+  out.save.fetch = saveIfChanged
+  out.save.reload = saveIfChanged
+  out.save.submit = saveIfChanged
+
   // keep track of isDirty as doc changes, use effectScope to handle isDirty state reactivity for cached data
   const scope = effectScope(true)
   scope.run(() => {
@@ -217,6 +226,25 @@ export function createDocumentResource(options, vm) {
     )
   }
 
+  // diff out.doc against the loaded doc and return only the changed fields, so
+  // read-only standard fields (owner, creation, modified, docstatus, idx, ...)
+  // are not included in the set_value payload, which the server rejects with
+  // "Cannot edit standard fields"
+  function getChangedFields() {
+    let doc = JSON.parse(JSON.stringify(out.doc || {}))
+    let originalDoc = out.originalDoc || {}
+    let values = {}
+    for (let key in doc) {
+      if (JSON.stringify(doc[key]) !== JSON.stringify(originalDoc[key])) {
+        values[key] = doc[key]
+      }
+    }
+    // never send identity/meta fields even if they appear changed
+    delete values.doctype
+    delete values.name
+    return values
+  }
+
   function reload() {
     return out.get.fetch()
   }

package/src/resources/documentResource.test.ts

@@ -0,0 +1,111 @@
+/**
+ * @vitest-environment node
+ */
+
+import { nextTick } from 'vue'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createDocumentResource } from './documentResource'
+import { setConfig } from '../utils/config'
+
+// A doc as returned by frappe.client.get — includes read-only standard fields
+const STANDARD_FIELDS = {
+  owner: 'Administrator',
+  creation: '2026-06-26 17:25:10',
+  modified: '2026-06-26 17:25:10',
+  modified_by: 'Administrator',
+  docstatus: 0,
+  idx: 0,
+}
+
+function makeServerDoc(doctype: string, name: string, overrides = {}) {
+  return {
+    doctype,
+    name,
+    ...STANDARD_FIELDS,
+    status: 'Open',
+    title: 'Original title',
+    ...overrides,
+  }
+}
+
+describe('documentResource save', () => {
+  // captures the params passed to frappe.client.set_value by the save resource
+  let capturedSetValueParams: any = null
+
+  beforeEach(() => {
+    capturedSetValueParams = null
+    setConfig('resourceFetcher', async (options: any) => {
+      if (options.url === 'frappe.client.set_value') {
+        capturedSetValueParams = options.params
+        // server echoes back the full doc on update
+        return makeServerDoc(
+          options.params.doctype,
+          options.params.name,
+          options.params.fieldname,
+        )
+      }
+      if (options.url === 'frappe.client.get') {
+        return makeServerDoc(options.params.doctype, options.params.name)
+      }
+      throw new Error(`unexpected request to ${options.url}`)
+    })
+  })
+
+  afterEach(() => {
+    setConfig('resourceFetcher', undefined)
+  })
+
+  it('sends only changed fields and strips standard fields', async () => {
+    const doc = createDocumentResource(
+      { doctype: 'CRM Deal', name: 'DEAL-0001', auto: false },
+      {},
+    )
+
+    await doc.get.fetch()
+    expect(doc.doc.owner).toBe('Administrator') // standard fields are present locally
+
+    doc.doc.status = 'Proposal/Quotation'
+    await nextTick()
+
+    await doc.save.submit()
+
+    const fieldname = capturedSetValueParams.fieldname
+    // only the changed field is sent
+    expect(fieldname).toEqual({ status: 'Proposal/Quotation' })
+    // none of the standard fields leak into the payload
+    for (const key of Object.keys(STANDARD_FIELDS)) {
+      expect(fieldname).not.toHaveProperty(key)
+    }
+    // identity fields are not part of fieldname
+    expect(fieldname).not.toHaveProperty('doctype')
+    expect(fieldname).not.toHaveProperty('name')
+  })
+
+  it('does not send a request when nothing changed', async () => {
+    const doc = createDocumentResource(
+      { doctype: 'CRM Deal', name: 'DEAL-0002', auto: false },
+      {},
+    )
+
+    await doc.get.fetch()
+    await doc.save.submit()
+
+    // save short-circuits with no pending changes, so set_value is never hit
+    expect(capturedSetValueParams).toBe(null)
+  })
+
+  it('sends only the changed subset when multiple fields exist', async () => {
+    const doc = createDocumentResource(
+      { doctype: 'CRM Deal', name: 'DEAL-0003', auto: false },
+      {},
+    )
+
+    await doc.get.fetch()
+    doc.doc.title = 'Updated title'
+    await nextTick()
+
+    await doc.save.submit()
+
+    expect(capturedSetValueParams.fieldname).toEqual({ title: 'Updated title' })
+  })
+})

package/src/resources/listResource.d.ts

@@ -0,0 +1,33 @@
+import type { Resource, ResourceOptions } from './resources'
+
+export interface ListResource<TRow = any> {
+  doctype: string
+  data: TRow[] | null
+  originalData: TRow[] | null
+  dataMap: Record<string, TRow>
+  list: Resource<TRow[]>
+  fetchOne: Resource<TRow[]>
+  insert: Resource<TRow>
+  setValue: Resource<TRow>
+  delete: Resource
+  runDocMethod: Resource
+  update: (options: ResourceOptions) => void
+  fetch: () => void
+  reload: () => Promise<TRow[] | null>
+  setData: (data: TRow[] | ((current: TRow[] | null) => TRow[])) => void
+  getRow: (name: string | number) => TRow | undefined
+  [key: string]: any
+}
+
+export function createListResource<TRow = any>(
+  options: ResourceOptions,
+  vm?: any,
+): ListResource<TRow>
+
+export function getCachedListResource<TRow = any>(
+  cacheKey: unknown,
+): ListResource<TRow> | null
+
+export function updateRowInListResource(doctype: string, doc: any): void
+export function deleteRowInListResource(doctype: string, docname: string): void
+export function revertRowInListResource(doctype: string, doc: any): void

package/src/resources/plugin.d.ts

@@ -0,0 +1,7 @@
+import type { App } from 'vue'
+
+declare const resourcesPlugin: {
+  install(app: App, options?: any): void
+}
+
+export default resourcesPlugin

package/src/resources/resources.d.ts

@@ -0,0 +1,35 @@
+export interface ResourceOptions {
+  [key: string]: any
+}
+
+export interface Resource<TData = any> {
+  method?: string
+  url?: string
+  data: TData | null
+  previousData: TData | null
+  loading: boolean
+  fetched: boolean
+  error: unknown
+  promise: Promise<TData> | null
+  auto?: boolean
+  params: unknown
+  fetch: (...args: any[]) => Promise<TData | null>
+  reload: (...args: any[]) => Promise<TData | null>
+  submit: (...args: any[]) => Promise<TData | null>
+  abort: () => void
+  reset: () => void
+  update: (options: ResourceOptions) => void
+  setData: (data: TData | ((current: TData | null) => TData)) => void
+  [key: string]: any
+}
+
+export function createResource<TData = any>(
+  options: string | ResourceOptions,
+  vm?: any,
+): Resource<TData>
+
+export function getCacheKey(cacheKey: unknown): string | null
+
+export function getCachedResource<TData = any>(
+  cacheKey: unknown,
+): Resource<TData> | null