frappe-ui 1.0.0-beta.65 → 1.0.0-beta.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-ui",
-  "version": "1.0.0-beta.65",
+  "version": "1.0.0-beta.66",
   "description": "A set of components and utilities for rapid UI development",
   "engines": {
     "node": ">=20.19.0"
@@ -20,7 +20,8 @@
   },
   "bin": {
     "tokens-v2": "./tailwind/migrate-tokens-v2.js",
-    "shortcuts-v1": "./scripts/migrate-shortcuts-v1.js"
+    "shortcuts-v1": "./scripts/migrate-shortcuts-v1.js",
+    "destinations-v1": "./scripts/migrate-destinations-v1.js"
   },
   "scripts": {
     "test": "vitest --run",

package/scripts/migrate-destinations-v1.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/** Rename pre-v1 navigation props to the v1 destination vocabulary.
+ * Usage: destinations-v1 [--dry-run] <dir-or-file...>
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const USAGE = 'Usage: destinations-v1 [--dry-run] <dir-or-file...>'
+const EXTENSIONS = new Set(['.vue', '.md'])
+const PROP_RENAMES = {
+  Button: { link: 'href' },
+  PageHeaderBackButton: { to: 'fallback-route' },
+  ListRow: { to: 'route' },
+  SidebarItem: { to: 'route' },
+  SidebarRailItem: { to: 'route' },
+  MobileNavItem: { to: 'route' },
+}
+const kebab = (name) =>
+  name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+
+function componentAliases(source) {
+  const aliases = new Map()
+  const imports =
+    /import\s*\{([^}]+)\}\s*from\s*['"]frappe-ui(?:\/[^'"]*)?['"]/g
+  for (const match of source.matchAll(imports)) {
+    for (const binding of match[1].split(',')) {
+      const [imported, local] = binding
+        .trim()
+        .replace(/^type\s+/, '')
+        .split(/\s+as\s+/)
+      if (PROP_RENAMES[imported]) {
+        const binding = local || imported
+        aliases.set(binding, imported)
+        aliases.set(kebab(binding), imported)
+      }
+    }
+  }
+  // Local template bindings shadow imports with the same local name.
+  const localImports =
+    /import\s+([^'";]+?)\s+from\s*['"](?!frappe-ui(?:\/|['"]))[^'"]+['"]/g
+  for (const match of source.matchAll(localImports)) {
+    const clause = match[1].trim()
+    const bindings = []
+    if (!clause.startsWith('{') && !clause.startsWith('*')) {
+      bindings.push(clause.split(',')[0].trim())
+    }
+    const named = clause.match(/\{([^}]+)\}/)?.[1]
+    if (named) {
+      for (const binding of named.split(',')) {
+        bindings.push(
+          binding
+            .trim()
+            .split(/\s+as\s+/)
+            .at(-1),
+        )
+      }
+    }
+    for (const name of bindings) {
+      if (!PROP_RENAMES[name]) continue
+      aliases.delete(name)
+      aliases.delete(kebab(name))
+    }
+  }
+  return aliases
+}
+
+function renameAttributes(tag, renames) {
+  let migrated = ''
+  let cursor = 0
+  let quote
+  while (cursor < tag.length) {
+    const character = tag[cursor]
+    if (quote) {
+      migrated += character
+      if (character === quote && tag[cursor - 1] !== '\\') quote = undefined
+      cursor += 1
+      continue
+    }
+    if (character === '"' || character === "'") {
+      quote = character
+      migrated += character
+      cursor += 1
+      continue
+    }
+    if (!/\s/.test(character)) {
+      migrated += character
+      cursor += 1
+      continue
+    }
+    migrated += character
+    cursor += 1
+    const match = tag
+      .slice(cursor)
+      .match(
+        /^(v-bind:|[:.]?)([A-Za-z][\w-]*)((?:\.[A-Za-z][\w-]*)*)(?=[\s=/>])/,
+      )
+    if (!match) continue
+    const replacement = renames[match[2]]
+    if (replacement) {
+      const isShorthandBinding =
+        match[1] && tag[cursor + match[0].length] !== '='
+      migrated += `${match[1]}${replacement}${match[3]}`
+      if (isShorthandBinding) migrated += `="${match[2]}"`
+    } else {
+      migrated += match[0]
+    }
+    cursor += match[0].length
+  }
+  return migrated
+}
+
+function migrateMarkup(source, aliases) {
+  let migrated = ''
+  let cursor = 0
+  while (cursor < source.length) {
+    const start = source.indexOf('<', cursor)
+    if (start === -1) return migrated + source.slice(cursor)
+    migrated += source.slice(cursor, start)
+    if (source.startsWith('<!--', start)) {
+      const commentEnd = source.indexOf('-->', start + 4)
+      const next = commentEnd === -1 ? source.length : commentEnd + 3
+      migrated += source.slice(start, next)
+      cursor = next
+      continue
+    }
+    const nameMatch = source.slice(start + 1).match(/^([A-Za-z][\w.-]*)/)
+    if (!nameMatch) {
+      migrated += '<'
+      cursor = start + 1
+      continue
+    }
+    let end = start + 1 + nameMatch[1].length
+    let quote
+    for (; end < source.length; end += 1) {
+      const character = source[end]
+      if (quote) {
+        if (character === quote && source[end - 1] !== '\\') quote = undefined
+      } else if (character === '"' || character === "'") {
+        quote = character
+      } else if (character === '>') {
+        break
+      }
+    }
+    if (end === source.length) return migrated + source.slice(start)
+    const tag = source.slice(start, end + 1)
+    const component = aliases.get(nameMatch[1])
+    if (!component) {
+      migrated += tag
+      cursor = end + 1
+      continue
+    }
+    migrated += renameAttributes(tag, PROP_RENAMES[component])
+    cursor = end + 1
+  }
+  return migrated
+}
+
+/**
+ * Rename destination attributes on template components explicitly imported
+ * from frappe-ui, leaving scripts and ambiguous global components unchanged.
+ */
+export function migrateDestinations(source) {
+  const aliases = componentAliases(source)
+  const templateStart = source.indexOf('<template')
+  const templateEnd = source.lastIndexOf('</template>')
+  if (templateStart === -1 || templateEnd < templateStart)
+    return migrateMarkup(source, aliases)
+  const end = templateEnd + '</template>'.length
+  return (
+    source.slice(0, templateStart) +
+    migrateMarkup(source.slice(templateStart, end), aliases) +
+    source.slice(end)
+  )
+}
+
+function filesIn(target, seen = new Set()) {
+  const stat = fs.lstatSync(target)
+  if (stat.isSymbolicLink()) return []
+  if (stat.isFile()) return EXTENSIONS.has(path.extname(target)) ? [target] : []
+  const real = fs.realpathSync(target)
+  if (seen.has(real)) return []
+  seen.add(real)
+  return fs
+    .readdirSync(target, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((entry) => {
+      if (['node_modules', '.git', 'dist', 'build'].includes(entry.name))
+        return []
+      return filesIn(path.join(target, entry.name), seen)
+    })
+}
+
+/** Run the destinations-v1 CLI and return its process exit code. */
+export function run(argv) {
+  const dryRun = argv.includes('--dry-run')
+  const unknown = argv.find((arg) => arg.startsWith('-') && arg !== '--dry-run')
+  if (unknown) {
+    console.error(`Unknown option: ${unknown}\n${USAGE}`)
+    return 1
+  }
+  const targets = argv.filter((arg) => arg !== '--dry-run')
+  if (!targets.length) {
+    console.error(USAGE)
+    return 1
+  }
+  let changed = 0
+  const files = [
+    ...new Set(targets.flatMap((target) => filesIn(path.resolve(target)))),
+  ]
+  for (const file of files) {
+    const source = fs.readFileSync(file, 'utf8')
+    const migrated = migrateDestinations(source)
+    if (migrated === source) continue
+    changed += 1
+    if (!dryRun) fs.writeFileSync(file, migrated)
+    console.log(`${dryRun ? 'Would migrate' : 'Migrated'} ${file}`)
+  }
+  console.log(
+    `${dryRun ? 'Would migrate' : 'Migrated'} ${changed} file${changed === 1 ? '' : 's'}.`,
+  )
+  return 0
+}
+
+const script = fileURLToPath(import.meta.url)
+const isMain =
+  process.argv[1] &&
+  fs.realpathSync(process.argv[1]) === fs.realpathSync(script)
+if (isMain) process.exitCode = run(process.argv.slice(2))

package/src/components/Button/Button.api.md

@@ -83,8 +83,8 @@
     type: 'string | kt | Tt'
   },
   {
-    name: 'link',
-    description: 'External link URL',
+    name: 'href',
+    description: 'External URL, opened in a new tab.',
     required: false,
     type: 'string'
   },

package/src/components/Button/Button.cy.ts

@@ -167,10 +167,10 @@ describe('<Button />', () => {
     cy.get('button').should('not.exist')
   })
 
-  it('renders an anchor when link is provided', () => {
+  it('renders an anchor when href is provided', () => {
     cy.mount(Button, {
       props: {
-        link: 'https://frappe.io/docs',
+        href: 'https://frappe.io/docs',
         label: 'Docs',
       },
     })
@@ -193,7 +193,7 @@ describe('<Button />', () => {
     cy.get('button').should('be.disabled')
   })
 
-  it('falls back to a disabled button when route or link is blocked', () => {
+  it('falls back to a disabled button when route or href is blocked', () => {
     const router = createTestRouter()
 
     cy.mount(Button, {
@@ -211,7 +211,7 @@ describe('<Button />', () => {
 
     cy.mount(Button, {
       props: {
-        link: 'https://frappe.io/docs',
+        href: 'https://frappe.io/docs',
         loading: true,
         loadingText: 'Loading docs',
         label: 'Docs',

package/src/components/Button/Button.vue

@@ -251,11 +251,11 @@ export default defineComponent({
       if (!isDisabled.value && props.route) {
         return { is: RouterLink, props: { to: props.route } }
       }
-      if (!isDisabled.value && props.link) {
+      if (!isDisabled.value && props.href) {
         return {
           is: 'a',
           props: {
-            href: props.link,
+            href: props.href,
             target: '_blank',
             rel: 'noreferrer noopener',
           },

package/src/components/Button/types.ts

@@ -43,8 +43,8 @@ export const buttonProps = {
     type: [String, Object] as PropType<RouterLinkProps['to']>,
     default: undefined,
   },
-  /** External link URL */
-  link: { type: String, default: undefined },
+  /** External URL, opened in a new tab. */
+  href: { type: String, default: undefined },
   /** Native button type */
   type: {
     type: String as PropType<'button' | 'submit' | 'reset'>,

package/src/components/MobileNav/MobileNav.api.md

@@ -26,14 +26,20 @@
     type: 'string | Component'
   },
   {
-    name: 'to',
+    name: 'route',
     description: 'Navigation target. Renders a router link. Tapping the item while it is\nalready the current route scrolls the shell to the top instead of\nre-navigating.',
     required: false,
     type: 'string | kt | Tt'
   },
+  {
+    name: 'href',
+    description: 'External URL. Used when `route` is absent; renders a native same-tab anchor.',
+    required: false,
+    type: 'string'
+  },
   {
     name: 'active',
-    description: 'Highlight this item. Independent of the current route so one tab can stay\nlit across a whole section (e.g. Home across community routes). Defaults to\nwhether `to` resolves to the current route.',
+    description: 'Highlight this item. Independent of the current route so one tab can stay\nlit across a whole section (e.g. Home across community routes). Defaults to\nwhether `route` resolves to the current route.',
     required: false,
     type: 'boolean'
   }

package/src/components/MobileNav/MobileNav.cy.ts

@@ -35,7 +35,7 @@ describe('<MobileNav />', () => {
 })
 
 describe('<MobileNavItem />', () => {
-  it('renders a button and emits click when there is no `to`', () => {
+  it('renders a button and emits click when there is no destination', () => {
     const onClick = cy.stub().as('click')
     cy.mount(MobileNavItem, { props: { label: 'Home', icon: 'lucide-house', onClick } })
     cy.get('button[data-slot=mobile-nav-item]').should('exist')
@@ -45,15 +45,28 @@ describe('<MobileNavItem />', () => {
 
   it('renders a router link to a different route', () => {
     cy.mount(MobileNavItem, {
-      props: { label: 'Search', icon: 'lucide-search', to: '/search' },
+      props: { label: 'Search', icon: 'lucide-search', route: '/search' },
       global: { plugins: [routerAt('/')] },
     })
     cy.get('a[data-slot=mobile-nav-item]').should('have.attr', 'href', '/search')
   })
 
-  it('is a button (not a link) when `to` is already the current route', () => {
+  it('renders a plain anchor for href', () => {
     cy.mount(MobileNavItem, {
-      props: { label: 'Home', icon: 'lucide-house', to: '/' },
+      props: { label: 'Docs', icon: 'lucide-book-open', href: 'https://frappe.io/docs' },
+    })
+    cy.get('a[data-slot=mobile-nav-item]').should('have.attr', 'href', 'https://frappe.io/docs')
+
+    cy.mount(MobileNavItem, {
+      props: { label: 'Route wins', route: '/search', href: 'https://frappe.io/docs' },
+      global: { plugins: [routerAt('/')] },
+    })
+    cy.get('a[data-slot=mobile-nav-item]').should('have.attr', 'href', '/search')
+  })
+
+  it('is a button (not a link) when `route` is already the current route', () => {
+    cy.mount(MobileNavItem, {
+      props: { label: 'Home', icon: 'lucide-house', route: '/' },
       global: { plugins: [routerAt('/')] },
     })
     cy.get('button[data-slot=mobile-nav-item]').should('exist')
@@ -69,7 +82,7 @@ describe('<MobileNavItem />', () => {
     registerShellScrollContainer(scroller)
 
     cy.mount(MobileNavItem, {
-      props: { label: 'Home', icon: 'lucide-house', to: '/' },
+      props: { label: 'Home', icon: 'lucide-house', route: '/' },
       global: { plugins: [routerAt('/')] },
     })
     cy.get('button[data-slot=mobile-nav-item]').click()

package/src/components/MobileNav/MobileNav.md

@@ -9,18 +9,19 @@ the bar adapts to any number of items.
 ## MobileNavItem
 
 Each item takes a `label`, an `icon` (or a default slot for custom content like
-an avatar), and a `to` target. It renders a router link when navigating
-somewhere new, and — when it's already the current route — a button that scrolls
-the shell's scroll container to the top instead of re-navigating.
+an avatar), and a `route` or `href` target (`route` takes precedence). `href`
+renders a native same-tab anchor. A `route` renders a link when navigating
+somewhere new and — when it is already current — a button that scrolls the
+shell's scroll container to the top instead of re-navigating.
 
 `active` controls the highlight and is independent of the current route, so one
 tab can stay lit across a whole section (e.g. Home across every community route)
 while tapping it still navigates home. When `active` is omitted it defaults to
-whether `to` matches the current route. The default slot receives `{ active }`
+whether `route` matches the current route. The default slot receives `{ active }`
 so custom content — an avatar, a badge — can react to the highlight:
 
 ```vue
-<MobileNavItem label="You" :to="{ name: 'More' }" :active="isMoreRoute">
+<MobileNavItem label="You" :route="{ name: 'More' }" :active="isMoreRoute">
   <template #default="{ active }">
     <UserAvatar :user="me" :class="{ 'ring-2 ring-outline-gray-4': active }" />
   </template>

package/src/components/MobileNav/MobileNavItem.vue

@@ -9,7 +9,7 @@
   -->
   <component
     :is="linkComponent"
-    v-if="to && !isCurrent"
+    v-if="(route && !isCurrent) || (!route && href)"
     v-bind="linkAttrs"
     data-slot="mobile-nav-item"
     :data-state="resolvedActive ? 'active' : 'inactive'"
@@ -94,15 +94,19 @@ defineSlots<{
 const globals = getCurrentInstance()?.appContext.config.globalProperties
 const hasRouter = computed(() => Boolean(globals?.$router))
 
-const linkComponent = computed(() => (hasRouter.value ? RouterLink : 'a'))
+const linkComponent = computed(() =>
+  props.route && hasRouter.value ? RouterLink : 'a',
+)
 const linkAttrs = computed(() =>
-  hasRouter.value
-    ? { to: props.to }
-    : { href: typeof props.to === 'string' ? props.to : undefined },
+  props.route
+    ? hasRouter.value
+      ? { to: props.route }
+      : { href: typeof props.route === 'string' ? props.route : undefined }
+    : { href: props.href },
 )
 
 const resolvedRoute = computed(() =>
-  props.to && globals?.$router ? globals.$router.resolve(props.to) : null,
+  props.route && globals?.$router ? globals.$router.resolve(props.route) : null,
 )
 
 // Is this item's target the exact current route? Drives scroll-vs-navigate and

package/src/components/MobileNav/types.ts

@@ -22,12 +22,15 @@ export interface MobileNavItemProps {
    * already the current route scrolls the shell to the top instead of
    * re-navigating.
    */
-  to?: RouteLocationRaw
+  route?: RouteLocationRaw
+
+  /** External URL. Used when `route` is absent; renders a native same-tab anchor. */
+  href?: string
 
   /**
    * Highlight this item. Independent of the current route so one tab can stay
    * lit across a whole section (e.g. Home across community routes). Defaults to
-   * whether `to` resolves to the current route.
+   * whether `route` resolves to the current route.
    */
   active?: boolean
 }

package/src/components/PageHeader/PageHeader.api.md

@@ -88,7 +88,7 @@
 
   const pageHeaderBackButtonProps = [
   {
-    name: 'to',
+    name: 'fallbackRoute',
     description: 'Fallback destination, used only when there is no in-app history to go back to\n(a cold load onto a deep link). Taps otherwise go back through history.',
     required: false,
     type: 'string | kt | Tt'

package/src/components/PageHeader/PageHeader.cy.ts

@@ -1,6 +1,8 @@
 import { defineComponent, h } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
 import PageHeader from './PageHeader.vue'
 import PageHeaderBase from './PageHeaderBase.vue'
+import PageHeaderBackButton from './PageHeaderBackButton.vue'
 import PageHeaderTarget from './PageHeaderTarget.vue'
 import PageHeaderMobile from './PageHeaderMobile.vue'
 import PageHeaderMobileTitle from './PageHeaderMobileTitle.vue'
@@ -70,6 +72,28 @@ describe('PageHeader', () => {
   })
 })
 
+describe('PageHeaderBackButton', () => {
+  it('uses fallbackRoute after a cold load', () => {
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes: [
+        { path: '/new', component: { render: () => null } },
+        { path: '/drafts', component: { render: () => null } },
+      ],
+    })
+    router.push('/new')
+    cy.wrap(router.isReady()).then(() => {
+      cy.mount(PageHeaderBackButton, {
+        props: { fallbackRoute: '/drafts' },
+        global: { plugins: [router] },
+      })
+      cy.get('button').click().then(() => {
+        expect(router.currentRoute.value.fullPath).to.equal('/drafts')
+      })
+    })
+  })
+})
+
 describe('PageHeaderTitle', () => {
   it('renders `title`, overridden by the default slot', () => {
     cy.mount(PageHeaderTitle, { props: { title: 'From prop' } })

package/src/components/PageHeader/PageHeader.md

@@ -15,8 +15,9 @@ Keeps its title centered regardless of the `#left` / `#right` control widths, on
 a single line with a trailing ellipsis.
 
 `PageHeaderBackButton` goes back through history, the way the browser's own back
-button does. It only navigates to `to` when there is no in-app history to go
-back to, so give it a `to` that makes the page recoverable on a cold load.
+button does. It only navigates to `fallbackRoute` when there is no in-app
+history to go back to, so give it a fallback that makes the page recoverable
+on a cold load.
 
 <ComponentPreview name="PageHeader-Mobile" />
 

package/src/components/PageHeader/PageHeaderBackButton.vue

@@ -21,6 +21,6 @@ const props = withDefaults(defineProps<PageHeaderBackButtonProps>(), {
 const router = useRouter()
 
 function onClick() {
-  navigateBack(router, props.to)
+  navigateBack(router, props.fallbackRoute)
 }
 </script>

package/src/components/PageHeader/types.ts

@@ -15,7 +15,7 @@ export interface PageHeaderBackButtonProps {
    * Fallback destination, used only when there is no in-app history to go back to
    * (a cold load onto a deep link). Taps otherwise go back through history.
    */
-  to?: RouteLocationRaw
+  fallbackRoute?: RouteLocationRaw
 
   /** Accessible label for the button. */
   label?: string

package/src/components/PageHeader/useHeaderBack.ts

@@ -52,13 +52,13 @@ function whenNavigationSettles(router: Router): Promise<void> {
 }
 
 /**
- * Go back the way the browser's back button would, and fall back to `to` when that
- * is not possible.
+ * Go back the way the browser's back button would, and fall back to
+ * `fallbackRoute` when that is not possible.
  *
  * A back button that always navigates to a fixed destination is not a back button:
  * it drops the user wherever the page author guessed they came from, which is wrong
- * for every other entry path into that page. So history wins, and `to` is only the
- * recovery route for when there is no history to walk.
+ * for every other entry path into that page. So history wins, and
+ * `fallbackRoute` is only the recovery route for when there is no history to walk.
  *
  * The post-navigation check covers entries that bounce: a guard that rejects the pop,
  * or a previous entry that redirects straight back to where we already are. Without
@@ -66,15 +66,15 @@ function whenNavigationSettles(router: Router): Promise<void> {
  */
 export async function navigateBack(
   router: Router,
-  to?: RouteLocationRaw,
+  fallbackRoute?: RouteLocationRaw,
 ): Promise<void> {
-  if (!to) {
+  if (!fallbackRoute) {
     router.back()
     return
   }
 
   if (!hasAppHistory(router)) {
-    await router.push(to)
+    await router.push(fallbackRoute)
     return
   }
 
@@ -84,6 +84,6 @@ export async function navigateBack(
   await settled
 
   if (router.currentRoute.value.fullPath === origin) {
-    await router.push(to)
+    await router.push(fallbackRoute)
   }
 }

package/src/components/Sidebar/Sidebar.api.md

@@ -76,14 +76,20 @@
     type: 'string'
   },
   {
-    name: 'to',
+    name: 'route',
     description: 'Navigation target. When set the row\'s main area renders as a router link;\notherwise it renders as a button. A click still invokes `onClick`.',
     required: false,
     type: 'string | kt | Tt'
   },
+  {
+    name: 'href',
+    description: 'External URL. Used when `route` is absent; renders a native same-tab anchor.',
+    required: false,
+    type: 'string'
+  },
   {
     name: 'active',
-    description: 'Marks the row active (`data-state="active"`). When omitted, active state is\ninferred by matching `to` against the current route.',
+    description: 'Marks the row active (`data-state="active"`). When omitted, active state is\ninferred by matching `route` against the current route.',
     required: false,
     type: 'boolean'
   },

package/src/components/Sidebar/Sidebar.cy.ts

@@ -121,13 +121,22 @@ describe('<SidebarSection />', () => {
 })
 
 describe('<SidebarItem />', () => {
-  it('renders a router link when `to` is set, a button otherwise', () => {
+  it('renders links for `route` and `href`, and a button otherwise', () => {
     cy.mount(SidebarItem, {
-      props: { label: 'Deals', to: '/deals' },
+      props: { label: 'Deals', route: '/deals' },
       global: { plugins: [createTestRouter()] },
     })
     cy.get('a[href="/deals"]').should('exist')
 
+    cy.mount(SidebarItem, { props: { label: 'Docs', href: 'https://frappe.io/docs' } })
+    cy.get('[data-slot=sidebar-item] > a').should('have.attr', 'href', 'https://frappe.io/docs')
+
+    cy.mount(SidebarItem, {
+      props: { label: 'Route wins', route: '/deals', href: 'https://frappe.io/docs' },
+      global: { plugins: [createTestRouter()] },
+    })
+    cy.get('[data-slot=sidebar-item] > a').should('have.attr', 'href', '/deals')
+
     const onClick = cy.stub().as('click')
     cy.mount(SidebarItem, { props: { label: 'Action', onClick } })
     cy.get('button').should('exist').click()
@@ -158,7 +167,7 @@ describe('<SidebarItem />', () => {
   it('keeps a #suffix options button a sibling of the link (not nested inside it)', () => {
     const onOptions = cy.stub().as('options')
     cy.mount(SidebarItem, {
-      props: { label: 'Design', to: '/design' },
+      props: { label: 'Design', route: '/design' },
       slots: {
         suffix: () =>
           h('button', { 'data-test': 'options', onClick: onOptions }, '...'),
@@ -172,7 +181,7 @@ describe('<SidebarItem />', () => {
   })
 
   it('is keyboard reachable and shows a visible focus-visible outline', () => {
-    cy.mount(SidebarItem, { props: { label: 'Design', to: '/design' } })
+    cy.mount(SidebarItem, { props: { label: 'Design', route: '/design' } })
     cy.get('a')
       .focus()
       .should('have.focus')

package/src/components/Sidebar/Sidebar.md

@@ -35,9 +35,11 @@ trailing zone, so an options menu in `#suffix` isn't nested inside the link
   adornments like a lock icon here next to the text.
 - `#suffix` — the trailing zone: an unread count, an options `…` menu, etc.
 
-Set `to` to render a router link; omit it for a button. `active` drives
-`data-state`; when omitted it's inferred by matching `to` against the current
-route. A click invokes `onClick` (bound from `@click`) in both cases.
+Set `route` to render a router link or `href` for a native same-tab anchor;
+`route` takes precedence when both are set. Omit both for a button. `active` drives
+`data-state`; when omitted it's inferred by matching
+`route` against the current route. A click invokes `onClick` (bound from
+`@click`) in every case.
 
 ## SidebarHeader
 

package/src/components/Sidebar/SidebarItem.vue

@@ -19,7 +19,7 @@
     -->
     <component
       :is="linkComponent"
-      v-if="to"
+      v-if="route || href"
       v-bind="linkAttrs"
       :accesskey="accessKey"
       :aria-label="tooltipText || undefined"
@@ -117,7 +117,14 @@
 </template>
 
 <script setup lang="ts">
-import { computed, getCurrentInstance, inject, onMounted, ref, useTemplateRef } from 'vue'
+import {
+  computed,
+  getCurrentInstance,
+  inject,
+  onMounted,
+  ref,
+  useTemplateRef,
+} from 'vue'
 import { RouterLink } from 'vue-router'
 import Tooltip from '../Tooltip/Tooltip.vue'
 import SidebarItemIcon from './SidebarItemIcon.vue'
@@ -163,16 +170,20 @@ const globals = getCurrentInstance()?.appContext.config.globalProperties
 const hasRouter = computed(() => Boolean(globals?.$router))
 
 // With a router, render RouterLink; without one, degrade to a plain <a> (with an
-// href only when `to` is a string — we can't resolve a route-location object).
-const linkComponent = computed(() => (hasRouter.value ? RouterLink : 'a'))
+// href only when `route` is a string — we can't resolve a route-location object).
+const linkComponent = computed(() =>
+  props.route && hasRouter.value ? RouterLink : 'a',
+)
 const linkAttrs = computed(() =>
-  hasRouter.value
-    ? { to: props.to }
-    : { href: typeof props.to === 'string' ? props.to : undefined },
+  props.route
+    ? hasRouter.value
+      ? { to: props.route }
+      : { href: typeof props.route === 'string' ? props.route : undefined }
+    : { href: props.href },
 )
 
 const resolvedRoute = computed(() =>
-  props.to && globals?.$router ? globals.$router.resolve(props.to) : null,
+  props.route && globals?.$router ? globals.$router.resolve(props.route) : null,
 )
 
 // Explicit `active` wins; otherwise infer from the current route so

package/src/components/Sidebar/types.ts

@@ -49,11 +49,14 @@ export interface SidebarItemProps {
    * Navigation target. When set the row's main area renders as a router link;
    * otherwise it renders as a button. A click still invokes `onClick`.
    */
-  to?: RouteLocationRaw
+  route?: RouteLocationRaw
+
+  /** External URL. Used when `route` is absent; renders a native same-tab anchor. */
+  href?: string
 
   /**
    * Marks the row active (`data-state="active"`). When omitted, active state is
-   * inferred by matching `to` against the current route.
+   * inferred by matching `route` against the current route.
    */
   active?: boolean
 

package/src/components/SidebarRail/SidebarRail.api.md

@@ -32,11 +32,17 @@
     type: 'string | Component'
   },
   {
-    name: 'to',
+    name: 'route',
     description: 'Navigation target. When set, the item renders as a router link; otherwise\nit renders as a button. A `click` event fires in both cases.',
     required: false,
     type: 'string | kt | Tt'
   },
+  {
+    name: 'href',
+    description: 'External URL. Used when `route` is absent; renders a native same-tab anchor.',
+    required: false,
+    type: 'string'
+  },
   {
     name: 'active',
     description: 'Marks the item as the current destination (indicator bar / active fill).',

package/src/components/SidebarRail/SidebarRail.cy.ts

@@ -32,7 +32,7 @@ describe('<SidebarRail />', () => {
 })
 
 describe('<SidebarRailItem />', () => {
-  it('renders a button and emits click when there is no `to`', () => {
+  it('renders a button and emits click when there is no destination', () => {
     const onClick = cy.stub().as('click')
     cy.mount(SidebarRailItem, {
       props: { label: 'Search', icon: 'lucide-search', onClick },
@@ -42,9 +42,20 @@ describe('<SidebarRailItem />', () => {
     cy.get('@click').should('have.been.calledOnce')
   })
 
-  it('renders a router link when `to` is set', () => {
+  it('renders links for `route` and `href`', () => {
     cy.mount(SidebarRailItem, {
-      props: { label: 'Search', icon: 'lucide-search', to: '/search' },
+      props: { label: 'Search', icon: 'lucide-search', route: '/search' },
+      global: { plugins: [createTestRouter()] },
+    })
+    cy.get('a[data-slot=sidebar-rail-item]').should('have.attr', 'href', '/search')
+
+    cy.mount(SidebarRailItem, {
+      props: { label: 'Docs', icon: 'lucide-book-open', href: 'https://frappe.io/docs' },
+    })
+    cy.get('a[data-slot=sidebar-rail-item]').should('have.attr', 'href', 'https://frappe.io/docs')
+
+    cy.mount(SidebarRailItem, {
+      props: { label: 'Route wins', route: '/search', href: 'https://frappe.io/docs' },
       global: { plugins: [createTestRouter()] },
     })
     cy.get('a[data-slot=sidebar-rail-item]').should('have.attr', 'href', '/search')

package/src/components/SidebarRail/SidebarRail.md

@@ -27,7 +27,8 @@ an optional unread `badge`. Two visual treatments:
 - `variant="ghost"` — transparent until hovered, raised when active. Pass an
   `icon` for a shortcut like Search or Notifications.
 
-Set `to` to render a router link; omit it to get a button that emits `click`.
+Set `route` to render a router link or `href` for a native same-tab anchor;
+`route` takes precedence when both are set. Omit both to get a button that emits `click`.
 The `badge` count shows as a pill (`badgeStyle="count"`) or a dot
 (`badgeStyle="dot"`); either way it folds into the item's accessible label, and
 a dot surfaces the real number in the tooltip. The badge pill teleports to

package/src/components/SidebarRail/SidebarRailItem.vue

@@ -6,15 +6,15 @@
   -->
   <Tooltip side="right">
     <!--
-      Link vs. button are split with v-if/v-else rather than a dynamic
-      <component :is>: a raw 'button' string there resolves to a
-      globally-registered <Button> in consumer apps, and reka's trigger can't
-      forward its element ref through a functional wrapper. The inner content is
-      identical in both branches.
+      Router and plain links share a dynamic component. The button stays a
+      literal v-else because a raw 'button' string can resolve to the globally
+      registered <Button> in consumer apps. The inner content is identical in
+      both branches.
     -->
-    <RouterLink
-      v-if="to"
-      :to="to"
+    <component
+      :is="route ? RouterLink : 'a'"
+      v-if="route || href"
+      v-bind="route ? { to: route } : { href }"
       data-slot="sidebar-rail-item"
       :data-variant="variant"
       :data-state="active ? 'active' : 'inactive'"
@@ -43,7 +43,7 @@
         />
       </slot>
       <SidebarRailItemBadge :count="badge" :variant="badgeStyle" />
-    </RouterLink>
+    </component>
 
     <button
       v-else

package/src/components/SidebarRail/types.ts

@@ -21,7 +21,10 @@ export interface SidebarRailItemProps {
    * Navigation target. When set, the item renders as a router link; otherwise
    * it renders as a button. A `click` event fires in both cases.
    */
-  to?: RouteLocationRaw
+  route?: RouteLocationRaw
+
+  /** External URL. Used when `route` is absent; renders a native same-tab anchor. */
+  href?: string
 
   /** Marks the item as the current destination (indicator bar / active fill). */
   active?: boolean

package/src/components/TabButtons/TabButtons.md

@@ -111,12 +111,11 @@ entries:
 - `theme`, `variant`, `size`, `loading`, `prefix` on individual options are no
   longer honored. Use `Button` or `Pill` directly if you need per-tab theming or
   a loading spinner.
-- `hideLabel` on options is gone. Use `icon` for an icon-only tab — its `label`,
-  if provided, is automatically exposed as accessibility text. Use `iconLeft`
+- `hideLabel` on options is gone. Use `icon` for an icon-only tab — its required
+  string `label` is automatically exposed as accessibility text. Use `iconLeft`
   for an accent icon before a visible label, and the `#suffix` slot for
   trailing content.
 - `route` and `href` on options are honored: a tab renders as a `<RouterLink>`
   when `route` is set, or an `<a href target=_blank>` when `href` is set.
-- The per-tab `tooltip` value surfaces as the native `title` attribute rather
-  than the floating `<Tooltip>` popover. Wrap the `TabButtons` instance in a
-  custom tooltip if you need styled behavior.
+- The per-tab `tooltip` field is removed. Put help text in app-owned UI when a
+  label alone is not enough.

package/src/components/TabButtons/TabButtons.vue

@@ -59,11 +59,11 @@ watchEffect(() => {
 
 const resolvedButtons = computed(() => {
   return options.value.map((button) => {
-    const { value, label, icon, tooltip } = button
+    const { value, label, icon } = button
 
     const isIconOnly = Boolean(icon)
     const visibleLabel = hasLabel(label) && !isIconOnly
-    const accessibleLabel = hasLabel(label) ? String(label) : tooltip
+    const accessibleLabel = hasLabel(label) ? label : undefined
 
     return {
       ...button,
@@ -355,7 +355,7 @@ function tabElementProps(button: (typeof resolvedButtons.value)[number]) {
           :title="
             button.accessibleLabel && !button.visibleLabel
               ? button.accessibleLabel
-              : button.tooltip
+              : undefined
           "
           :class="[
             tabShellClasses,

package/src/components/TabButtons/types.ts

@@ -11,13 +11,12 @@ export type TabButtonValue = TabValue
 export type TabButtonIcon = TabIcon
 export interface TabButton {
   value: TabButtonValue
-  label?: string | number
+  label: string
   /** Icon-only tab; `label` becomes accessibility text. */
   icon?: TabButtonIcon
   /** Leading accent icon, rendered next to the visible label. */
   iconLeft?: TabButtonIcon
   disabled?: boolean
-  tooltip?: string
   /** Renders the tab as a `<RouterLink>` to the given target. */
   route?: RouteLocationRaw
   /** Renders the tab as an `<a href>`, opens in a new tab. */
@@ -51,7 +50,15 @@ export interface TabButtonsEmits {
 
 export interface TabButtonsSlots {
   /** Slot before the tab button label. */
-  prefix?: (props: { button: TabButton; checked: boolean; disabled: boolean }) => any
+  prefix?: (props: {
+    button: TabButton
+    checked: boolean
+    disabled: boolean
+  }) => any
   /** Slot after the tab button label. */
-  suffix?: (props: { button: TabButton; checked: boolean; disabled: boolean }) => any
+  suffix?: (props: {
+    button: TabButton
+    checked: boolean
+    disabled: boolean
+  }) => any
 }

package/src/molecules/list/List.cy.ts

@@ -66,22 +66,24 @@ describe('List (feed mode)', () => {
       })
   })
 
-  it('renders rows as links with `to`, buttons with a click listener, divs otherwise', () => {
+  it('renders rows with `route` or `href` as links, click rows as buttons, and static rows as divs', () => {
     const clicked = cy.spy().as('rowClick')
     cy.mount(
       {
         render: () =>
           h(List, () => [
-            feedRow('1', { to: { name: 'Item', params: { id: '1' } } }),
+            feedRow('1', { route: { name: 'Item', params: { id: '1' } } }),
+            feedRow('external', { href: 'https://frappe.io' }),
             feedRow('2', { onClick: clicked }),
             feedRow('3'),
           ]),
       },
       { global: { plugins: [makeRouter()] } },
     )
-    cy.get('a[data-slot=list-row]')
+    cy.get('a[data-slot=list-row]').eq(0)
       .should('have.attr', 'href', '/item/1')
       .and('have.attr', 'data-interactive')
+    cy.get('a[data-slot=list-row]').eq(1).should('have.attr', 'href', 'https://frappe.io')
     cy.get('button[data-slot=list-row]').click()
     cy.get('@rowClick').should('have.been.calledOnce')
     cy.get('div[data-slot=list-row]').should('exist')
@@ -94,7 +96,7 @@ describe('List (feed mode)', () => {
         render: () => [
           h(RouterView),
           h(List, () => [
-            feedRow('1', { to: { name: 'Item', params: { id: '1' } } }),
+            feedRow('1', { route: { name: 'Item', params: { id: '1' } } }),
           ]),
         ],
       },

package/src/molecules/list/ListRow.vue

@@ -2,7 +2,7 @@
   <!-- `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 }">
+  <RouterLink v-if="route" :to="route" custom v-slot="{ href, navigate }">
     <ListRowBase
       tag="a"
       :href="href"
@@ -12,6 +12,9 @@
       <slot />
     </ListRowBase>
   </RouterLink>
+  <ListRowBase v-else-if="href" tag="a" :href="href" :value="value" @click="onClick">
+    <slot />
+  </ListRowBase>
   <ListRowBase
     v-else
     :tag="isInteractive() ? 'button' : 'div'"

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

@@ -67,11 +67,17 @@
 
   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.',
+    name: 'route',
+    description: 'Renders the row as a RouterLink. Without `route` or `href`, a row with a click\nlistener renders as a button; otherwise a plain div.',
     required: false,
     type: 'string | kt | Tt'
   },
+  {
+    name: 'href',
+    description: 'External URL. Used when `route` is absent; renders a native same-tab anchor.',
+    required: false,
+    type: 'string'
+  },
   {
     name: 'value',
     description: 'Row key — the `selection` key when `selectable` and the `v-model:active`\nkey. Required whenever the list uses either.',

package/src/molecules/list/list.md

@@ -12,8 +12,9 @@ Not to be confused with the config-driven `ListView` in `frappe-ui/experimental`
 ## 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 — real interactive elements,
+content, and a right-aligned trailing cell. Rows with `route` render as
+RouterLinks, rows with `href` as native same-tab anchors, and rows with a click
+listener as buttons — real interactive elements,
 so a row is clickable _or_ carries inline action buttons, never both (nested
 interactive controls are invalid HTML); [row actions](#row-actions) shows how to
 combine them. `selectable` reveals the animated checkbox column and switches row
@@ -58,7 +59,7 @@ 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`
+unlike `selectable`, activation is additive, so the row's own `@click` and `route`
 navigation still run. It's single-select and independent of the multi-select
 checkbox `selection` — and works in feed or column mode.
 

package/src/molecules/list/types.ts

@@ -83,10 +83,13 @@ export interface ListProps {
 
 export interface ListRowProps {
   /**
-   * Renders the row as a RouterLink. Without `to`, a row with a click
+   * Renders the row as a RouterLink. Without `route` or `href`, a row with a click
    * listener renders as a button; otherwise a plain div.
    */
-  to?: RouteLocationRaw
+  route?: RouteLocationRaw
+
+  /** External URL. Used when `route` is absent; renders a native same-tab anchor. */
+  href?: string
 
   /**
    * Row key — the `selection` key when `selectable` and the `v-model:active`