frappe-ui 1.0.0-beta.0 → 1.0.0-beta.1

package/frappe/Link/Link.api.md

@@ -0,0 +1,114 @@
+<!-- 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 propsData = [
+  {
+    name: 'doctype',
+    description: '',
+    required: true,
+    type: 'string'
+  },
+  {
+    name: 'filters',
+    description: '',
+    required: false,
+    type: 'Record<string, unknown>',
+    default: '{}'
+  },
+  {
+    name: 'creatable',
+    description: '',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'disabled',
+    description: '',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'label',
+    description: 'Label rendered above (or beside, for binary controls) the input.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'description',
+    description: 'Helper text rendered below the input.\nHidden when `error` is set.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'error',
+    description: 'Error message rendered below the input. When set, the control receives\n`aria-invalid="true"` and `data-state="invalid"`. May be either a string\nor an `Error` object whose `messages?: string[]` is rendered as stacked\nlines (with `Error.message` as the fallback).',
+    required: false,
+    type: 'string | FrappeUIError'
+  },
+  {
+    name: 'required',
+    description: 'Marks the field as required. Renders an asterisk next to the label and\nforwards `required` / `aria-required` to the underlying control.',
+    required: false,
+    type: 'boolean'
+  },
+  {
+    name: 'id',
+    description: 'HTML id of the underlying control. Auto-generated via `useId()` if omitted.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'modelValue',
+    description: '',
+    required: false,
+    type: 'string | null',
+    default: 'null'
+  },
+  {
+    name: 'open',
+    description: '',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  }
+]
+
+  const slotsData = [
+  {
+    name: 'suffix',
+    description: '',
+    type: '{ open: boolean; disabled: boolean; query: string; selectedOption: ComboboxSelectableOption | null; '
+  }
+]
+
+  const emitsData = [
+  {
+    name: 'update:modelValue',
+    description: 'Fired when the model value changes.',
+    type: 'unknown[]'
+  },
+  {
+    name: 'update:open',
+    description: 'Fired when the open state changes.',
+    type: 'unknown[]'
+  },
+  {
+    name: 'create',
+    description: '',
+    type: '[query: string]'
+  }
+]
+</script>
+## API Reference
+
+<PropsTable name="Link" :data="propsData"/> 
+
+<SlotsTable :data="slotsData"/> 
+
+<EmitsTable :data="emitsData"/> 
+

package/frappe/Link/Link.cy.ts

@@ -0,0 +1,215 @@
+import { defineComponent, h, ref } from 'vue'
+import Link from './Link.vue'
+
+const users = [
+  { value: 'alice', label: 'Alice' },
+  { value: 'bob', label: 'Bob' },
+  { value: 'carol', label: 'Carol' },
+]
+
+function stubSearchLink(rows = users) {
+  cy.intercept('POST', '/api/method/frappe.desk.search.search_link', {
+    statusCode: 200,
+    body: { message: rows },
+  }).as('searchLink')
+}
+
+describe('Link', () => {
+  beforeEach(() => {
+    stubSearchLink()
+  })
+
+  describe('rendering', () => {
+    it('emits data-slot="link" on the root wrapper', () => {
+      cy.mount(Link, { props: { doctype: 'User' } })
+      cy.get('[data-slot="link"]').should('exist')
+    })
+
+    it('forwards id/label/description/required to the underlying Combobox (P5)', () => {
+      cy.mount(Link, {
+        props: {
+          doctype: 'User',
+          id: 'user-picker',
+          label: 'User',
+          description: 'Pick a user',
+          required: true,
+        },
+      })
+
+      cy.get('label[for="user-picker"]').should('contain.text', 'User')
+      cy.get('[role="combobox"]#user-picker').should(
+        'have.attr',
+        'aria-required',
+        'true',
+      )
+      cy.contains('Pick a user').should('exist')
+    })
+
+    it('forwards `error` and wires aria-invalid', () => {
+      cy.mount(Link, {
+        props: {
+          doctype: 'User',
+          id: 'user-picker',
+          error: 'Boom',
+        },
+      })
+      cy.get('[role="combobox"]#user-picker').should(
+        'have.attr',
+        'aria-invalid',
+        'true',
+      )
+      cy.contains('Boom').should('exist')
+    })
+  })
+
+  describe('v-model', () => {
+    it('round-trips a selection', () => {
+      cy.mount(Link, {
+        props: {
+          doctype: 'User',
+          'onUpdate:modelValue': cy.spy().as('onUpdate'),
+        },
+      })
+
+      cy.wait('@searchLink')
+      cy.get('[role="combobox"]').click()
+      cy.contains('[role="option"]', 'Alice').click()
+      cy.get('@onUpdate').should('have.been.calledWith', 'alice')
+    })
+
+    it('clear sets the model to null (never the empty string)', () => {
+      const Host = defineComponent({
+        setup() {
+          const value = ref<string | null>('alice')
+          return { value }
+        },
+        render() {
+          return h(Link, {
+            doctype: 'User',
+            modelValue: this.value,
+            'onUpdate:modelValue': (v: string | null) => (this.value = v),
+          })
+        },
+      })
+
+      cy.mount(Host).then(({ component }) => {
+        const host = component as unknown as { value: string | null }
+        cy.get('[data-slot="clear"]').click({ force: true })
+        cy.then(() => expect(host.value).to.equal(null))
+      })
+    })
+  })
+
+  describe('default clear', () => {
+    it('renders a clear button when value is set and not required', () => {
+      cy.mount(Link, {
+        props: {
+          doctype: 'User',
+          modelValue: 'alice',
+          'onUpdate:modelValue': cy.spy().as('onUpdate'),
+        },
+      })
+      cy.get('[data-slot="clear"]').should('exist').click({ force: true })
+      cy.get('@onUpdate').should('have.been.calledWith', null)
+    })
+
+    it('suppresses the clear button when required is true', () => {
+      cy.mount(Link, {
+        props: { doctype: 'User', modelValue: 'alice', required: true },
+      })
+      cy.get('[data-slot="clear"]').should('not.exist')
+    })
+
+    it('suppresses the clear button when modelValue is empty', () => {
+      cy.mount(Link, { props: { doctype: 'User' } })
+      cy.get('[data-slot="clear"]').should('not.exist')
+    })
+  })
+
+  describe('creatable', () => {
+    it('does not render the Create row by default', () => {
+      cy.mount(Link, { props: { doctype: 'User' } })
+      cy.get('[role="combobox"]').click().type('zed')
+      cy.contains('[role="option"]', 'Create').should('not.exist')
+    })
+
+    it('shows the Create row only when query is non-empty', () => {
+      cy.mount(Link, { props: { doctype: 'User', creatable: true } })
+      cy.get('[role="combobox"]').click()
+      cy.contains('[role="option"]', 'Create').should('not.exist')
+      cy.get('[role="combobox"]').type('zed')
+      cy.contains('[role="option"]', 'Create').should('contain.text', 'zed')
+    })
+
+    it('emits @create with just the query (one argument)', () => {
+      cy.mount(Link, {
+        props: {
+          doctype: 'User',
+          creatable: true,
+          onCreate: cy.spy().as('onCreate'),
+        },
+      })
+      cy.get('[role="combobox"]').click().type('zed')
+      cy.contains('[role="option"]', 'Create').click()
+      cy.get('@onCreate').should('have.been.calledOnce')
+      cy.get('@onCreate').should('have.been.calledWith', 'zed')
+      cy.get('@onCreate').then((spy) => {
+        // Spec: @create is one-arg. Guard against the old (query, close) shape.
+        const callArgs = (spy as unknown as sinon.SinonSpy).getCall(0).args
+        expect(callArgs).to.have.length(1)
+      })
+    })
+  })
+
+  describe('v-model:open', () => {
+    it('emits update:open when the popover toggles', () => {
+      cy.mount(Link, {
+        props: {
+          doctype: 'User',
+          'onUpdate:open': cy.spy().as('onOpen'),
+        },
+      })
+      cy.get('[role="combobox"]').click()
+      cy.get('@onOpen').should('have.been.calledWith', true)
+    })
+  })
+
+  describe('exposed API', () => {
+    it('exposes a zero-arg reload() that re-fetches options', () => {
+      const Host = defineComponent({
+        setup() {
+          const link = ref<{ reload: () => void } | null>(null)
+          return { link }
+        },
+        render() {
+          return h(Link, { doctype: 'User', ref: 'link' })
+        },
+      })
+
+      cy.mount(Host).then(({ component }) => {
+        cy.wait('@searchLink')
+        cy.then(() => {
+          const exposed = (component as unknown as { link: { reload: () => void } }).link
+          expect(exposed.reload).to.be.a('function')
+          expect(exposed.reload.length).to.equal(0)
+          exposed.reload()
+        })
+        cy.wait('@searchLink')
+      })
+    })
+  })
+
+  describe('#suffix slot', () => {
+    it('replaces the default clear button', () => {
+      cy.mount(Link, {
+        props: { doctype: 'User', modelValue: 'alice' },
+        slots: {
+          suffix: () =>
+            h('button', { 'data-slot': 'redirect', type: 'button' }, 'Go'),
+        },
+      })
+      cy.get('[data-slot="clear"]').should('not.exist')
+      cy.get('[data-slot="redirect"]').should('exist')
+    })
+  })
+})

package/frappe/Link/Link.md

@@ -0,0 +1,38 @@
+# Link
+
+A single-record picker for a Frappe doctype. Composes `Combobox` and fetches its options directly from `frappe.desk.search.search_link` — pick a doctype, and the rest works.
+
+## Simple
+A bare picker. `v-model` carries the selected record's primary key (a string), or `null` when nothing is selected.
+
+<ComponentPreview csr="true" name="Link-Simple" layout="stacked" />
+
+## Labeling, Description, Error, Required
+`Link` accepts the standard input labeling props — `label`, `description`, `error`, `required` — and forwards them to the underlying `Combobox`, so ARIA wiring (`aria-required`, `aria-invalid`, `aria-errormessage`) and the InputLabel chrome render identically to a standalone `Combobox`.
+
+<ComponentPreview csr="true" name="Link-Labeling" />
+
+## Filters
+The `filters` prop is a `Record<string, unknown>` passed straight through to `search_link`. Frappe's underlying endpoint also accepts list-form and SQL-string filters, but the component boundary intentionally narrows to the dict form — it covers every CRM call site without leaking backend serialization into the public API. Reactive — changing `filters` triggers a refetch. The `#footer` slot is the canonical home for a filter-status row (or any non-selectable popover affordance) and renders below both the options list and the `creatable` create-new row.
+
+<ComponentPreview csr="true" name="Link-Filters" />
+
+## Creatable
+`creatable: true` injects a "Create" row at the bottom of the popover, visible only when the user has typed. Clicking it emits `@create` with the typed query — the consumer owns the create flow (typically a dialog) and assigns the freshly-created record back to `v-model` on success. To replace the default create row markup (icon, helper text, copy), supply the `#item-create` slot — scope is `{ query }`.
+
+<ComponentPreview csr="true" name="Link-Creatable" />
+
+## Suffix
+By default, Link renders a clear button in the suffix slot when `modelValue` is non-null and `required: false`. To replace it with your own affordance — an "Open record" link, an "Edit" button — supply `#suffix`. The slot fully takes over; if you still want a clear button alongside your action, render one yourself. To dismiss the options dropdown when your action takes over (e.g. opens a dialog), bind `v-model:open` and set it to `false`.
+
+<ComponentPreview csr="true" name="Link-Suffix" />
+
+## Member Picker
+`Link` forwards every `Combobox` per-row slot — `#item-prefix`, `#item-label`, `#item-suffix`, `#item` — so a doctype picker can render an avatar, role, or any other contextual chrome without dropping down to `<Combobox>` directly.
+
+<ComponentPreview csr="true" name="Link-MemberPicker" />
+
+## Combobox passthrough
+Link composes `Combobox` and forwards unrecognized props via `$attrs` and all non-overridden slots. Anything in the [`Combobox` API](../../docs/components/combobox) that Link doesn't claim itself (`options`, `loading`, and the `#suffix` / `#item-create` slots which have Link-specific defaults) reaches the underlying component unchanged.
+
+<!-- @include: ./Link.api.md -->

package/frappe/Link/Link.vue

@@ -1,52 +1,99 @@
 <template>
-  <div class="flex flex-col gap-1.5" :class="attrs.class" :style="attrs.style">
-    <FormLabel v-if="label" :label="label" size="sm" :required="required" />
+  <div data-slot="link" class="contents">
     <Combobox
+      ref="comboboxRef"
+      v-bind="$attrs"
       v-model="model"
-      :placeholder="placeholder || `Select ${doctype}`"
+      v-model:open="open"
+      class="group !gap-1"
+      :label="label"
+      :description="description"
+      :error="error"
+      :required="required"
+      :id="id"
       :options="linkOptions"
-      @input="handleInputChange"
+      :disabled="disabled"
+      :placeholder="placeholder ?? `Search ${doctype.toLowerCase()}`"
+      :loading="options.loading && !options.data"
+      @update:query="handleInputChange"
       @focus="() => loadOptions('')"
-      :open-on-focus="true"
-      v-bind="attrsWithoutClassStyle"
-      :variant="props.variant"
     >
-      <template #create-new="{ searchTerm }">
-        <LucidePlus class="size-4 mr-2" />
-        <span class="font-medium"> Create new {{ doctype }}</span>
+      <template
+        v-for="(_, name) in forwardedSlots"
+        #[name]="slotProps"
+        :key="name"
+      >
+        <slot :name="name" v-bind="slotProps" />
+      </template>
+
+      <template v-if="slots.suffix" #suffix="suffixProps">
+        <slot name="suffix" v-bind="suffixProps" />
+      </template>
+      <template v-else-if="showClear" #suffix>
+        <button
+          type="button"
+          aria-label="Clear"
+          data-slot="clear"
+          class="group-hover:grid group-focus:grid group-focus-within:grid hidden size-4 place-items-center rounded-sm text-ink-gray-5 hover:bg-surface-gray-3 hover:text-ink-gray-7 focus:outline-none focus-visible:ring-2 focus-visible:ring-outline-gray-3"
+          @click="clearValue"
+          @pointerdown.stop
+        >
+          <span class="lucide-x size-3.5" />
+        </button>
+      </template>
+
+      <template v-if="slots['item-create']" #item-create="slotProps">
+        <slot name="item-create" v-bind="slotProps" />
+      </template>
+      <template v-else #item-create="{ query }">
+        <div class="flex">
+          <span class="truncate">
+            Create
+            <span v-if="query" class="font-medium text-ink-gray-8">
+              {{ query }}
+            </span>
+          </span>
+        </div>
       </template>
     </Combobox>
   </div>
 </template>
 
 <script setup lang="ts">
-import { watch, useAttrs, computed } from 'vue'
-import { Combobox, type ComboboxOption } from '../../src/components/Combobox'
-import FormLabel from '../../src/components/FormLabel.vue'
+import { computed, ref, useSlots, watch } from 'vue'
+import { Combobox } from '../../src/components/Combobox'
+import type {
+  ComboboxCustomOption,
+  ComboboxOption,
+} from '../../src/components/Combobox/types'
 import debounce from '../../src/utils/debounce'
-// @ts-ignore - Vue SFC without explicit types
 import { createResource } from '../../src/resources'
 import { frappeRequest } from '../../src/utils/frappeRequest'
-import type { LinkProps, SelectOption } from './types'
-import LucidePlus from '~icons/lucide/plus'
+import type { LinkEmits, LinkExposed, LinkOption, LinkProps } from './types'
 
 const props = withDefaults(defineProps<LinkProps>(), {
-  label: '',
   filters: () => ({}),
-  variant: 'subtle',
+  creatable: false,
+  disabled: false,
 })
-const model = defineModel<string | null>({ default: '' })
-const emit = defineEmits<{
-  (e: 'create', searchTerm: string): void
-}>()
+
+const model = defineModel<string | null>({ default: null })
+const open = defineModel<boolean>('open', { default: false })
+const comboboxRef = ref<{ focus: () => void } | null>(null)
+
+const emit = defineEmits<LinkEmits>()
+
 defineOptions({ inheritAttrs: false })
 
-const attrs = useAttrs() as Record<string, any>
-const attrsWithoutClassStyle = computed(() => {
-  return Object.fromEntries(
-    Object.entries(attrs).filter(([key]) => key !== 'class' && key !== 'style'),
-  )
-})
+const slots = useSlots()
+
+const forwardedSlots = computed(() =>
+  Object.fromEntries(
+    Object.entries(slots).filter(
+      ([name]) => name !== 'suffix' && name !== 'item-create',
+    ),
+  ),
+)
 
 const options = createResource({
   url: 'frappe.desk.search.search_link',
@@ -57,31 +104,35 @@ const options = createResource({
   },
   method: 'POST',
   resourceFetcher: frappeRequest,
-  transform: (data: SelectOption[]) => {
-    return data.map((doc) => ({
+  transform: (data: LinkOption[]): LinkOption[] =>
+    data.map((doc: any) => ({
       label: doc.label || doc.value,
       value: doc.value,
-    }))
-  },
+      description: doc.description,
+    })),
 })
 
-const createNewOption = {
-  type: 'custom' as const,
-  key: 'create_new',
+const createNewOption: ComboboxCustomOption = {
+  type: 'custom',
+  key: 'create',
   label: 'Create New',
-  slotName: 'create-new',
-  condition: () => true,
+  slot: 'create',
+  condition: ({ query }: { query: string }) => Boolean(query.trim()),
   onClick: ({ query }) => emit('create', query),
-} as ComboboxOption
+}
 
-const linkOptions = computed(() => {
+const linkOptions = computed<ComboboxOption[]>(() => {
   const _options = options.data || []
-  if (props.allowCreate) {
+  if (props.creatable) {
     return [..._options, createNewOption]
   }
   return _options
 })
 
+const showClear = computed(
+  () => !props.disabled && !!model.value && !props.required,
+)
+
 const loadOptions = (txt: string = '') => {
   options.update({
     params: {
@@ -93,12 +144,20 @@ const loadOptions = (txt: string = '') => {
   options.reload()
 }
 
-const handleInputChange = debounce((inputString: string) => {
-  loadOptions(inputString || '')
+const handleInputChange = debounce((value: string) => {
+  loadOptions(value || '')
 }, 300)
 
+const clearValue = () => {
+  model.value = null
+  open.value = false
+  comboboxRef.value?.focus()
+}
+
 watch([() => props.doctype, () => props.filters], () => loadOptions(''), {
   immediate: true,
   deep: true,
 })
+
+defineExpose<LinkExposed>({ reload: () => loadOptions('') })
 </script>

package/frappe/Link/index.ts

@@ -1,2 +1,2 @@
 export { default as Link } from './Link.vue'
-export type { LinkProps } from './types'
+export type { LinkEmits, LinkExposed, LinkOption, LinkProps } from './types'

package/frappe/Link/stories/Creatable.vue

@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Link } from 'frappe-ui/frappe'
+import { useMockSearchLink, MOCK_LOST_REASONS } from './_mock'
+
+// Local copy of the seed list so created rows don't leak into the sibling
+// Labeling story on the same docs page. Both variations share this list —
+// pushing through either Link makes the new option visible in the other.
+const reasons = [...MOCK_LOST_REASONS]
+useMockSearchLink({ 'CRM Lost Reason': reasons })
+
+const reasonA = ref<string | null>(null)
+const openA = ref(false)
+const lastCreateA = ref<string | null>(null)
+
+function handleCreateA(query: string) {
+  // Real apps open a create dialog and persist the record; on success they
+  // assign the new primary key back to v-model. Here we mimic that flow:
+  // append to the mock dataset, select it, and close the popover.
+  if (!reasons.some((r) => r.value === query)) reasons.push({ value: query })
+  reasonA.value = query
+  openA.value = false
+  lastCreateA.value = query
+}
+
+const reasonB = ref<string | null>(null)
+const openB = ref(false)
+
+function handleCreateB(query: string) {
+  if (!reasons.some((r) => r.value === query)) reasons.push({ value: query })
+  reasonB.value = query
+  openB.value = false
+}
+</script>
+
+<template>
+  <div class="w-full !py-20 grid place-items-center">
+    <div class="grid w-96 gap-8">
+      <div class="grid gap-3">
+        <Link
+          v-model="reasonA"
+          v-model:open="openA"
+          doctype="CRM Lost Reason"
+          label="Lost reason"
+          placeholder="Select or create a reason"
+          creatable
+          @create="handleCreateA"
+        />
+
+        <div class="text-sm text-ink-gray-5">
+          Selected: <code class="text-ink-gray-7">{{ reasonA || 'None' }}</code>
+        </div>
+        <div v-if="lastCreateA" class="text-sm text-ink-gray-5">
+          Last <code>@create</code> query:
+          <code class="text-ink-gray-7">{{ lastCreateA }}</code>
+        </div>
+      </div>
+
+      <div class="grid gap-3">
+        <div class="text-base text-ink-gray-5">Customised create row</div>
+        <Link
+          v-model="reasonB"
+          v-model:open="openB"
+          doctype="CRM Lost Reason"
+          label="Lost reason"
+          placeholder="Type a new reason…"
+          creatable
+          @create="handleCreateB"
+        >
+          <template #item-create="{ query }">
+            <div class="flex items-center gap-2 min-w-0">
+              <span
+                class="lucide-plus size-3.5 text-ink-gray-5 shrink-0"
+              />
+              <span class="truncate">
+                Add new reason
+                <span
+                  v-if="query"
+                  class="font-medium text-ink-gray-8 italic"
+                >
+                  “{{ query }}”
+                </span>
+              </span>
+            </div>
+          </template>
+        </Link>
+
+        <p class="text-p-xs text-ink-gray-5">
+          Use <code>#item-create</code> to override the default create row —
+          add an icon, helper text, or any markup. Slot scope is
+          <code>{ query }</code>.
+        </p>
+      </div>
+    </div>
+  </div>
+</template>