frappe-ui 1.0.0-rc.1 → 1.0.0

package/experimental/Calendar/Calendar.api.md

@@ -3,6 +3,7 @@
   import PropsTable from '@/components/Docs/PropsTable.vue'
   import SlotsTable from '@/components/Docs/SlotsTable.vue'
   import EmitsTable from '@/components/Docs/EmitsTable.vue'
+  import ExposedTable from '@/components/Docs/ExposedTable.vue'
 
   const propsData = [
   {
@@ -95,6 +96,74 @@
     type: '[payload: { view: CalendarMode; startDate: string; endDate: string; }]'
   }
 ]
+
+  const exposedData = [
+  {
+    name: 'reloadEvents',
+    description: 'Rebuilds the calendar\'s own copy of `events`. The calendar already does\nthis whenever `events` changes.',
+    type: '() => void'
+  },
+  {
+    name: 'currentMonthYear',
+    description: 'The title of the visible range, e.g. "August 2026".',
+    type: 'string'
+  },
+  {
+    name: 'currentYear',
+    description: 'The year of the visible month.',
+    type: 'number'
+  },
+  {
+    name: 'currentMonth',
+    description: 'The visible month, `0` for January.',
+    type: 'number'
+  },
+  {
+    name: 'currentDay',
+    description: 'The day of the month the view is anchored on.',
+    type: 'number | null'
+  },
+  {
+    name: 'enabledModes',
+    description: 'The views that `config` does not disable. Read once, when the calendar\nmounts.',
+    type: 'CalendarActionOption[]'
+  },
+  {
+    name: 'activeView',
+    description: 'The visible view.',
+    type: 'CalendarMode'
+  },
+  {
+    name: 'decrement',
+    description: 'Moves back one day, week or month, depending on the view.',
+    type: '() => void'
+  },
+  {
+    name: 'increment',
+    description: 'Moves forward one day, week or month, depending on the view.',
+    type: '() => void'
+  },
+  {
+    name: 'updateActiveView',
+    description: 'Switches to this view.',
+    type: '(value: CalendarMode, d?: Date, isPreviousMonth?: boolean, isNextMonth?: boolean) => void'
+  },
+  {
+    name: 'setCalendarDate',
+    description: 'Jumps to this date, or to today when no date is given.',
+    type: '(d?: string | Date) => void'
+  },
+  {
+    name: 'onMonthYearChange',
+    description: 'Jumps to this date and moves the month picker to it.',
+    type: '(val?: string | Date) => void'
+  },
+  {
+    name: 'selectedMonthDate',
+    description: 'The month picker\'s date, as `YYYY-MM-DD`.',
+    type: 'string'
+  }
+]
 </script>
 
 ## API Reference
@@ -104,3 +173,5 @@
 <SlotsTable :data="slotsData"/>
 
 <EmitsTable :data="emitsData"/>
+
+<ExposedTable :data="exposedData"/>

package/experimental/Calendar/Calendar.vue

@@ -830,18 +830,37 @@ watch(
 )
 
 defineExpose({
+  /**
+   * Rebuilds the calendar's own copy of `events`. The calendar already does
+   * this whenever `events` changes.
+   */
   reloadEvents,
+  /** The title of the visible range, e.g. "August 2026". */
   currentMonthYear,
+  /** The year of the visible month. */
   currentYear,
+  /** The visible month, `0` for January. */
   currentMonth,
+  /** The day of the month the view is anchored on. */
   currentDay,
+  /**
+   * The views that `config` does not disable. Read once, when the calendar
+   * mounts.
+   */
   enabledModes,
+  /** The visible view. */
   activeView,
+  /** Moves back one day, week or month, depending on the view. */
   decrement,
+  /** Moves forward one day, week or month, depending on the view. */
   increment,
+  /** Switches to this view. */
   updateActiveView,
+  /** Jumps to this date, or to today when no date is given. */
   setCalendarDate,
+  /** Jumps to this date and moves the month picker to it. */
   onMonthYearChange,
+  /** The month picker's date, as `YYYY-MM-DD`. */
   selectedMonthDate,
 })
 </script>

package/experimental/ListView/ListView.api.md

@@ -3,6 +3,7 @@
   import PropsTable from '@/components/Docs/PropsTable.vue'
   import SlotsTable from '@/components/Docs/SlotsTable.vue'
   import EmitsTable from '@/components/Docs/EmitsTable.vue'
+  import ExposedTable from '@/components/Docs/ExposedTable.vue'
 
   const listViewProps = [
   {
@@ -55,6 +56,29 @@
   }
 ]
 
+  const listViewExposed = [
+  {
+    name: 'selections',
+    description: 'The keys (`rowKey` values) of the selected rows.',
+    type: 'Reactive<Set<unknown>>'
+  },
+  {
+    name: 'allRowsSelected',
+    description: 'Whether every enabled row is selected.',
+    type: 'boolean'
+  },
+  {
+    name: 'toggleRow',
+    description: 'Selects the row with this key, or deselects it if it is selected.',
+    type: '(row: any) => void'
+  },
+  {
+    name: 'toggleAllRows',
+    description: 'Selects every enabled row. Clears the selection instead when `select` is\nfalse or every row is already selected.',
+    type: '(select: any) => void'
+  }
+]
+
   const listEmptyStateSlots = [
   {
     name: 'default',
@@ -319,6 +343,8 @@
 
 <EmitsTable :data="listViewEmits"/>
 
+<ExposedTable :data="listViewExposed"/>
+
 ### ListEmptyState
 
 <SlotsTable :data="listEmptyStateSlots"/>

package/experimental/ListView/ListView.vue

@@ -170,9 +170,16 @@ provide(
 )
 
 defineExpose({
+  /** The keys (`rowKey` values) of the selected rows. */
   selections,
+  /** Whether every enabled row is selected. */
   allRowsSelected,
+  /** Selects the row with this key, or deselects it if it is selected. */
   toggleRow,
+  /**
+   * Selects every enabled row. Clears the selection instead when `select` is
+   * false or every row is already selected.
+   */
   toggleAllRows,
 })
 </script>

package/experimental/MultiEmailInput/MultiEmailInput.vue

@@ -15,7 +15,7 @@ import {
 } from 'reka-ui'
 import Avatar from '../../src/components/Avatar/Avatar.vue'
 import ItemListRow from '../../src/components/ItemListRow/ItemListRow.vue'
-import { LoadingIndicator } from '../../src/components/LoadingIndicator'
+import { Spinner } from '../../src/components/Spinner'
 import {
   InputDescription,
   InputError,
@@ -377,7 +377,7 @@ defineSlots<MultiEmailInputSlots>()
               data-slot="loading"
               class="flex items-center gap-2 px-2 py-1.5 text-base text-ink-gray-5"
             >
-              <LoadingIndicator class="size-4" />
+              <Spinner class="size-4" />
               <span>{{ loadingText }}</span>
             </div>
 

package/experimental/TextEditor/components/MediaNodeView.vue

@@ -3,7 +3,7 @@
 import { ref, onMounted, onUnmounted, computed, h } from 'vue'
 import { NodeViewWrapper, nodeViewProps } from '@tiptap/vue-3'
 import { Button } from '#components/Button'
-import { LoadingIndicator } from '#components/LoadingIndicator'
+import { Spinner } from '#components/Spinner'
 import Tooltip from '#components/Tooltip/Tooltip.vue'
 import { localFileMap } from '../extensions/image/image-extension'
 import { ErrorMessage } from '#components/ErrorMessage'
@@ -375,7 +375,7 @@ const wrapperClasses = (float: string) => [
           <div
             class="bg-gray-900/80 p-2 inset-0 leading-none rounded-1 flex flex-col items-center justify-center gap-2">
             <div class="flex items-center gap-2">
-              <LoadingIndicator class="text-gray-100 size-4" />
+              <Spinner class="text-gray-100 size-4" />
               <span class="text-gray-100">Uploading {{ isVideo ? 'video' : 'image' }}...</span>
             </div>
           </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-ui",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0",
   "description": "A set of components and utilities for rapid UI development",
   "engines": {
     "node": ">=20.19.0"
@@ -50,7 +50,7 @@
     "test": "vitest --run",
     "test:coverage": "vitest --run --coverage",
     "test:cypress": "cypress run --component",
-    "test:cypress:coverage": "cross-env COVERAGE=true cypress run --component",
+    "test:cypress:coverage": "cross-env COVERAGE=true cypress run --component && nyc report",
     "coverage": "yarn test:coverage && yarn test:cypress:coverage && yarn coverage:merge",
     "coverage:merge": "tsx .github/scripts/merge-coverage.ts",
     "type-check": "vue-tsc --noEmit -p tsconfig.app.json && vue-tsc --noEmit -p tsconfig.node.json",
@@ -310,7 +310,6 @@
     "@codemirror/lang-xml": "^6.1.0",
     "@codemirror/lang-yaml": "^6.1.3",
     "@codemirror/lint": "^6.0.0",
-    "@cypress/code-coverage": "^3.13.10",
     "@shikijs/transformers": "^3.15.0",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^3.2.4",

package/readme.md

@@ -3,116 +3,176 @@
 <img src="https://github.com/user-attachments/assets/0a81cdc1-d957-47a9-b151-f5571be0d038" width="80" />
 
 # Frappe UI
-**Rapidly build modern frontends for Frappe apps**
 
-<img alt="NPM Downloads" src="https://img.shields.io/npm/dm/frappe-ui.svg?style=flat"/>
+**The all-in-one toolkit for modern frontends. High-quality components, app recipes and AI-ready docs.**
+
+<a href="https://www.npmjs.com/package/frappe-ui"><img alt="npm version" src="https://img.shields.io/npm/v/frappe-ui.svg?style=flat" /></a>
+<a href="https://www.npmjs.com/package/frappe-ui"><img alt="npm downloads" src="https://img.shields.io/npm/dm/frappe-ui.svg?style=flat" /></a>
+<a href="./license.md"><img alt="MIT license" src="https://img.shields.io/npm/l/frappe-ui.svg?style=flat" /></a>
 
 <a href="https://ui.frappe.io">
-<img width="1292" alt="Screenshot 2024-12-12 at 5 27 58 PM" src="https://github.com/user-attachments/assets/56800b45-2859-4dc5-92b8-e40959ce4902" />
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="./assets/readme-hero-dark.png" />
+<img width="1392" alt="The Button page on the Frappe UI documentation site" src="./assets/readme-hero-light.png" />
+</picture>
 </a>
-</div>
-
-## Frappe UI
-
-Frappe UI provides a set of components and utilities for rapid UI development. Components are built using Vue 3 and Tailwind.
-Along with generic components like Button, Link, Dialog, etc., it also contains utilities for handling server-side data fetching, directives and utilities.
-
-
-### Motivation
-In 2019, I began building [Frappe Books](https://github.com/frappe/books) which had a new design. This led to the creation of small reusable components like Button, Dialog, and Card. Moving on to [Frappe Cloud](https://github.com/frappe/press) in 2020, I reused and evolved these components in the Frappe Cloud UI. In 2022, while starting a new project, I decided to extract these components into a standalone package to avoid repeating the copy-paste process. This package is now being developed alongside the [Gameplan](https://github.com/frappe/gameplan), continually adding generic components and utilities for frontend development.
 
-### Under the Hood
+[Documentation](https://ui.frappe.io) ·
+[Getting started](https://ui.frappe.io/docs/getting-started) ·
+[Migration guide](https://ui.frappe.io/docs/migration) ·
+[Changelog](https://ui.frappe.io/docs/changelog)
 
-- [TailwindCSS](https://github.com/tailwindlabs/tailwindcss): Utility first CSS Framework to build design system based UI.
-- [Reka UI](https://github.com/unovue/reka-ui): Unstyled and accessible UI primitives.
-- [TipTap](https://github.com/ueberdosis/tiptap): ProseMirror based rich-text editor with a Vue API.
-- [dayjs](https://github.com/iamkun/dayjs): Minimal javascript library for working with dates.
-
-## Links
-
-- [Documentation](https://ui.frappe.io)
-- [Vite Plugins](vite/README.md)
-- [Frappe UI Starter Boilerplate](https://github.com/netchampfaris/frappe-ui-starter)
-- [Community](https://github.com/frappe/frappe-ui/discussions)
-
-## Usage
+</div>
 
-Requires **Node `>=20.19.0`**, Vite, Vue 3 and Tailwind CSS v3.4.
+## What you get
+
+- **50+ components.** Buttons, form controls, dialogs, popovers, tabs, sidebars,
+  app shells and more. Built with [Vue 3](https://vuejs.org),
+  [Tailwind CSS](https://tailwindcss.com) and [Reka UI](https://reka-ui.com)
+  primitives.
+- **Design tokens with dark mode built in.** Semantic `surface`, `ink` and
+  `outline` color tokens, plus radius, typography and elevation scales. Tokens
+  flip under `[data-theme="dark"]`, so a `dark:` variant is never needed.
+- **Data composables for Frappe.** `useCall`, `useList`, `useDoc`, `useDoctype`
+  and `useNewDoc` handle fetching, caching, pagination and writes against a
+  Frappe backend.
+- **Rich text editor, lists and charts** as separate entries: `frappe-ui/editor`
+  (TipTap), `frappe-ui/list` and `frappe-ui/charts` (ECharts).
+- **Vite plugins** for the Frappe dev-server proxy, Lucide icon auto-imports,
+  DocType type generation and production builds.
+- **TypeScript first.** Every core component ships typed props, slots and emits.
+- **Recipes.** Eight full app screens built with frappe-ui, such as mail,
+  tickets, deals and accounting, each with a desktop and a mobile layout. See
+  them on the [home page](https://ui.frappe.io).
+- **Agent skills.** An [agent skill](./skills/frappe-ui/) and
+  [llms.txt](https://ui.frappe.io/llms.txt) teach Claude Code, Cursor, Codex
+  and similar tools how to use the library. See
+  [Using with AI agents](#using-with-ai-agents).
+
+## Quick start
+
+Requires **Node `>=20.19.0`**, **Vite**, **Vue `>=3.5`** and **Tailwind CSS
+`>=3.4 <4`**.
 
 ```sh
 npm install frappe-ui
-# or
-yarn add frappe-ui
 ```
 
-Add the frappe-ui Vite plugin in `vite.config.js`:
+Add the Vite plugin in `vite.config.js`:
 
 ```js
+import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import frappeui from 'frappe-ui/vite'
 
-export default {
+export default defineConfig({
   plugins: [frappeui(), vue()],
-}
+})
 ```
 
-Add the preset and frappe-ui's source globs in `tailwind.config.js`:
+Add the preset and content globs in `tailwind.config.js`:
 
 ```js
-import frappeUIPreset, { content } from 'frappe-ui/tailwind'
+import preset, { content } from 'frappe-ui/tailwind'
 
 export default {
-  presets: [frappeUIPreset],
-  content: ['./index.html', './src/**/*.{vue,js,ts}', ...content],
+  presets: [preset],
+  content: [...content, './index.html', './src/**/*.{vue,js,ts}'],
 }
 ```
 
-Import the stylesheet once, from your CSS entry:
+Import the stylesheet once from your CSS entry:
 
 ```css
 @import 'frappe-ui/style.css';
 ```
 
-Now use the components:
+Wrap your app root in `FrappeUIProvider` and start using components:
 
 ```vue
 <script setup>
-import { Button } from 'frappe-ui'
+import { FrappeUIProvider, Button, useList } from 'frappe-ui'
+
+const todos = useList({
+  doctype: 'ToDo',
+  fields: ['name', 'description'],
+  filters: { status: 'Open' },
+})
 </script>
 
 <template>
-  <Button variant="solid" icon-left="lucide-plus">Click me</Button>
+  <FrappeUIProvider>
+    <ul>
+      <li v-for="todo in todos.data" :key="todo.name">
+        {{ todo.description }}
+      </li>
+    </ul>
+    <Button variant="solid" icon-left="lucide-plus" @click="todos.next()">
+      Load more
+    </Button>
+  </FrappeUIProvider>
 </template>
 ```
 
-The full setup, including TypeScript and the Frappe dev-server proxy, is on the
-[Getting Started](https://ui.frappe.io/docs/getting-started) page.
+The full setup, including the starter template and TypeScript, is on the
+[Installation](https://ui.frappe.io/docs/getting-started) page. The
+[Frappe app](https://ui.frappe.io/docs/getting-started/frappe) guide covers the
+dev-server proxy.
+
+## Package entries
 
-## Claude Code skill
+| Import                  | Contents                                                               |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `frappe-ui`             | Core components, data composables, `dialog` and `toast`, directives    |
+| `frappe-ui/editor`      | TipTap-based rich text editor, kits and extensions                     |
+| `frappe-ui/code-editor` | CodeMirror-based code editor and `CodeKit`                             |
+| `frappe-ui/list`        | Composable `List` family: rows, cells, headers, groups, sorting        |
+| `frappe-ui/charts`      | ECharts-based area, bar, line, donut, funnel, heatmap, sankey, scatter |
+| `frappe-ui/icons`       | Frappe's own icons, such as `StepsIcon` and `LightningIcon`            |
+| `frappe-ui/vite`        | Vite plugins                                                           |
+| `frappe-ui/tailwind`    | Tailwind preset and content globs                                      |
+| `frappe-ui/style.css`   | Base stylesheet, fonts and token variables                             |
 
-For AI coding agents (Claude Code, Cursor, Codex, etc.), Frappe UI ships an agent skill that teaches the agent the library's conventions — semantic Tailwind tokens, the `variant` + `theme` color axes, the `useCall` data-fetching composable, common UI recipes, and anti-patterns to avoid.
+## Using with AI agents
 
-Install with [Vercel's `skills` CLI](https://github.com/vercel-labs/skills):
+Install the frappe-ui skill in your coding agent:
 
 ```sh
 npx skills add https://github.com/frappe/frappe-ui/tree/main/skills/frappe-ui
 ```
 
-The skill lives in [`skills/frappe-ui/`](./skills/frappe-ui/) and is updated alongside the library.
+Or point it to [ui.frappe.io/llms.txt](https://ui.frappe.io/llms.txt), a list
+of every docs page.
+
+## Contributing
 
-## Used By
+```sh
+yarn                # install
+yarn dev            # component playground
+yarn docs:dev       # documentation site
+yarn test           # vitest
+yarn type-check     # vue-tsc
+```
 
-Frappe UI is being used in a lot of products by
-[Frappe](https://github.com/frappe).
+Before you change a public API, read [`PHILOSOPHY.md`](./PHILOSOPHY.md) for the
+design rules, [`CONTEXT.md`](./CONTEXT.md) for the shared vocabulary and
+[`spec/`](./spec/) for component contracts and decision records.
 
-- [Frappe Cloud](https://frappecloud.com)
-- [Gameplan](https://github.com/frappe/gameplan)
+## Used by
+
+- [Frappe Cloud](https://frappe.io/cloud)
+- [Frappe CRM](https://github.com/frappe/crm)
 - [Helpdesk](https://github.com/frappe/helpdesk)
-- [Frappe Insights](https://github.com/frappe/insights)
-- [Frappe Drive](https://github.com/frappe/drive)
-- [Frappe Builder](https://github.com/frappe/builder)
+- [Frappe HR](https://github.com/frappe/hrms)
+- [Frappe Learning](https://github.com/frappe/lms)
+- [Insights](https://github.com/frappe/insights)
+- [Builder](https://github.com/frappe/builder)
+- [Gameplan](https://github.com/frappe/gameplan)
+
+## License
+
+[MIT](./license.md)
 
-<br>
 <br>
 <div align="center">
 	<a href="https://frappe.io" target="_blank">

package/src/charts/FunnelChart.vue

@@ -121,10 +121,9 @@
         :dir="dir"
       >
         <template #default="slotProps">
+          <!-- The value item carries the stage's name, so a header would print
+               it twice. -->
           <slot name="tooltip" v-bind="slotProps">
-            <div class="mb-2 text-p-sm text-ink-gray-5">
-              {{ slotProps.label }}
-            </div>
             <div class="flex flex-col gap-1.5 text-p-sm">
               <div
                 v-for="item in slotProps.items.filter(
@@ -170,7 +169,7 @@
 
 <script setup lang="ts">
 import { computed, reactive, ref } from 'vue'
-import { formatLabel, formatPercent, formatValue } from './format'
+import { formatPercent, formatValue } from './format'
 import { buildFunnelStages, funnelShapes } from './funnelGeometry'
 import { useTooltipDismiss } from './core/useTooltipDismiss'
 import { paletteColors, useChartTokens } from './tokens'
@@ -290,7 +289,9 @@ function readStage(stage: FunnelStage) {
   tooltip.items = [
     {
       name: String(stage.index),
-      label: formatLabel(props.value),
+      // `value` is a row key, often one the caller named when reshaping its
+      // rows, so it says nothing to the reader.
+      label: stage.label,
       color: colors.value[stage.index],
       value: stage.value,
       formattedValue: formatMeasure(stage.value),

package/src/charts/axisChartCommon.ts

@@ -12,12 +12,14 @@ import {
 } from './format'
 import { CHART_FONT_FAMILY } from './measureText'
 import { paletteColors, type ChartTokens } from './tokens'
+import type { AxisChartFormatters } from './seriesData'
 import { mergeDeep } from './utils'
 import type {
   AxisChartBaseConfig,
   AxisChartConfig,
   AxisChartSeriesConfig,
   ChartMark,
+  ChartPalette,
   ChartPaletteName,
   ChartYAxisConfig,
 } from './types'
@@ -28,6 +30,8 @@ export type AxisChartOptionContext = {
   hiddenSeries?: string[]
   /** Plot width in pixels, once measured. Unset leaves pixel sizes to echarts. */
   width?: number
+  /** What a data label prints in when its series has no `format` of its own. */
+  format?: AxisChartFormatters
 }
 
 export const AXIS_LABEL_FONT_SIZE = 11
@@ -106,6 +110,35 @@ export const AXIS_LABEL_MARGIN = 8
 
 const DEFAULT_PALETTE: ChartPaletteName = 'sequential'
 
+/**
+ * The categorical ramp is five hue families, each a dark member then its light
+ * partner. Two strengths of one hue tangle where lines cross, so lines take the
+ * partners shifted one family along: no two neighbouring lines share a hue.
+ */
+const LINE_ORDER = [0, 3, 4, 7, 8, 1, 2, 5, 6, 9]
+
+/**
+ * One hue getting paler reads as a single series once two lines cross, so a
+ * chart of two or more lines, and nothing else, is drawn in separate hues. A
+ * bar among them keeps the sequential ramp: see `colorSlots`.
+ */
+function defaultPalette(
+  config: AxisChartConfig,
+  tokens: ChartTokens,
+): ChartPalette {
+  const lines = config.series.filter(
+    (series) => resolveMark(series, config, true) === 'line',
+  )
+  const ramp = tokens.categorical
+  if (
+    lines.length < 2 ||
+    lines.length < config.series.length ||
+    ramp.length !== LINE_ORDER.length
+  )
+    return DEFAULT_PALETTE
+  return LINE_ORDER.map((i) => ramp[i])
+}
+
 const MARKS: ChartMark[] = ['bar', 'line', 'area']
 
 /**
@@ -120,13 +153,9 @@ export function resolveSeriesColors(
   config: AxisChartConfig,
   tokens: ChartTokens,
 ): Record<string, string> {
-  const assigned = paletteColors(
-    config.palette,
-    tokens,
-    config.series.length,
-    DEFAULT_PALETTE,
-  )
-  const slots = colorSlots(config)
+  const palette = config.palette ?? defaultPalette(config, tokens)
+  const assigned = paletteColors(palette, tokens, config.series.length)
+  const slots = colorSlots(config, palette)
   const colors: Record<string, string> = {}
   config.series.forEach((series, index) => {
     colors[series.name] = series.color || assigned[slots[index]]
@@ -144,10 +173,9 @@ export function resolveSeriesColors(
  * list is drawn as it was written, a diverging ramp's direction is its meaning,
  * and a categorical set is unrelated hues with no ramp to reorder.
  */
-function colorSlots(config: AxisChartConfig): number[] {
+function colorSlots(config: AxisChartConfig, palette: ChartPalette): number[] {
   const identity = config.series.map((_, index) => index)
-  if (Array.isArray(config.palette)) return identity
-  if ((config.palette ?? DEFAULT_PALETTE) !== 'sequential') return identity
+  if (palette !== 'sequential') return identity
 
   const weights = config.series.map(
     (series) => INK_WEIGHT[resolveMark(series, config, true)],