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

package/src/components/SettingsDialog/SettingsDialog.api.md

@@ -0,0 +1,273 @@
+<!-- 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 settingsDialogProps = [
+  {
+    name: 'size',
+    description: 'Max-width size of the dialog.',
+    required: false,
+    type: 'DialogSize',
+    default: '"4xl"'
+  },
+  {
+    name: 'shortcut',
+    description: 'Enable the Cmd/Ctrl+Shift+, shortcut that toggles the dialog.',
+    required: false,
+    type: 'boolean',
+    default: 'true'
+  },
+  {
+    name: 'unmountOnHide',
+    description: 'Unmount a panel\'s content when its tab is inactive (reka-ui default: true).\nSet false to keep visited panels mounted (hidden) — preserves their state\nand scroll position across tab switches at the cost of memory.',
+    required: false,
+    type: 'boolean',
+    default: 'true'
+  },
+  {
+    name: 'modelValue',
+    description: 'Controls whether the dialog is open.',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'tab',
+    description: 'The selected tab — pairs with SettingsNavItem `:value` and SettingsPanel\n`:value`. Optional: leave unbound to let reka-ui manage selection internally,\nor bind `v-model:tab` to drive it (e.g. from the route).',
+    required: false,
+    type: 'string | number'
+  }
+]
+
+  const settingsDialogSlots = [
+  {
+    name: 'title',
+    description: 'Accessible dialog title (visually hidden). Defaults to "Settings".',
+    type: 'any'
+  },
+  {
+    name: 'description',
+    description: 'Accessible dialog description (visually hidden, for aria-describedby).',
+    type: 'any'
+  },
+  {
+    name: 'default',
+    description: 'Sidebar + content panes (compose SettingsSidebar and SettingsContent).',
+    type: 'any'
+  }
+]
+
+  const settingsDialogEmits = [
+  {
+    name: 'update:modelValue',
+    description: 'Fired when the model value changes.',
+    type: '[value: boolean]'
+  },
+  {
+    name: 'update:tab',
+    description: 'Fired when the tab changes.',
+    type: '[value: string | number | undefined]'
+  }
+]
+
+  const settingsSidebarSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const settingsNavGroupProps = [
+  {
+    name: 'label',
+    description: 'Group heading shown above its items.',
+    required: false,
+    type: 'string'
+  }
+]
+
+  const settingsNavGroupSlots = [
+  {
+    name: 'label',
+    description: '',
+    type: '{}'
+  },
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const settingsNavItemProps = [
+  {
+    name: 'value',
+    description: 'Unique tab id — must match the SettingsPanel `value` it controls.',
+    required: true,
+    type: 'string | number'
+  }
+]
+
+  const settingsNavItemSlots = [
+  {
+    name: 'default',
+    description: 'Item label.',
+    type: 'any'
+  },
+  {
+    name: 'prefix',
+    description: 'Leading icon or avatar.',
+    type: 'any'
+  },
+  {
+    name: 'suffix',
+    description: 'Trailing badge / count.',
+    type: 'any'
+  }
+]
+
+  const settingsContentSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const settingsPanelProps = [
+  {
+    name: 'value',
+    description: 'Unique tab id — must match the SettingsNavItem `value` that controls it.',
+    required: true,
+    type: 'string | number'
+  }
+]
+
+  const settingsPanelSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const settingsHeaderProps = [
+  {
+    name: 'title',
+    description: 'Convenience heading. Omit and use the default slot for a custom header.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'description',
+    description: 'Optional sub-heading under the title.',
+    required: false,
+    type: 'string'
+  }
+]
+
+  const settingsHeaderSlots = [
+  {
+    name: 'default',
+    description: 'Replaces the entire header (title/description/actions) with custom content.',
+    type: 'any'
+  },
+  {
+    name: 'actions',
+    description: 'Actions on the right of the default title header.',
+    type: 'any'
+  }
+]
+
+  const settingsBodySlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const settingsRowProps = [
+  {
+    name: 'title',
+    description: 'Setting name, rendered on the left.',
+    required: true,
+    type: 'string'
+  },
+  {
+    name: 'description',
+    description: 'Optional helper text under the title.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'labelFor',
+    description: 'Explicit id to associate the title label with. Overrides auto-detection.',
+    required: false,
+    type: 'string'
+  }
+]
+
+  const settingsRowSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+</script>
+
+## API Reference
+
+### SettingsDialog
+
+<PropsTable name="SettingsDialog" :data="settingsDialogProps"/>
+
+<SlotsTable :data="settingsDialogSlots"/>
+
+<EmitsTable :data="settingsDialogEmits"/>
+
+### SettingsSidebar
+
+<SlotsTable :data="settingsSidebarSlots"/>
+
+### SettingsNavGroup
+
+<PropsTable folder="SettingsDialog" name="SettingsNavGroup" :data="settingsNavGroupProps"/>
+
+<SlotsTable :data="settingsNavGroupSlots"/>
+
+### SettingsNavItem
+
+<PropsTable folder="SettingsDialog" name="SettingsNavItem" :data="settingsNavItemProps"/>
+
+<SlotsTable :data="settingsNavItemSlots"/>
+
+### SettingsContent
+
+<SlotsTable :data="settingsContentSlots"/>
+
+### SettingsPanel
+
+<PropsTable folder="SettingsDialog" name="SettingsPanel" :data="settingsPanelProps"/>
+
+<SlotsTable :data="settingsPanelSlots"/>
+
+### SettingsHeader
+
+<PropsTable folder="SettingsDialog" name="SettingsHeader" :data="settingsHeaderProps"/>
+
+<SlotsTable :data="settingsHeaderSlots"/>
+
+### SettingsBody
+
+<SlotsTable :data="settingsBodySlots"/>
+
+### SettingsRow
+
+<PropsTable folder="SettingsDialog" name="SettingsRow" :data="settingsRowProps"/>
+
+<SlotsTable :data="settingsRowSlots"/>

package/src/components/SettingsDialog/SettingsDialog.cy.ts

@@ -0,0 +1,126 @@
+import { defineComponent, h, ref } from 'vue'
+import SettingsDialog from './SettingsDialog.vue'
+import SettingsSidebar from './SettingsSidebar.vue'
+import SettingsNavGroup from './SettingsNavGroup.vue'
+import SettingsNavItem from './SettingsNavItem.vue'
+import SettingsContent from './SettingsContent.vue'
+import SettingsPanel from './SettingsPanel.vue'
+
+const panel = (text: string) =>
+  defineComponent({ render: () => h('div', { class: 'tab-panel' }, text) })
+
+const tabs = [
+  { label: 'Profile', value: 'profile', component: panel('Profile content') },
+  { label: 'General', value: 'general', component: panel('General content') },
+  { label: 'Members', value: 'members', component: panel('Members content') },
+]
+
+// A minimal consumer that wires the active tab the way an app would: the kit's
+// reka-ui Tabs owns selection, the consumer only binds `tab` and supplies a
+// matching `value` on each nav item and panel.
+const Harness = defineComponent({
+  props: { modelValue: { type: Boolean, default: true } },
+  emits: ['update:modelValue'],
+  setup(props, { emit }) {
+    const active = ref(tabs[0].value)
+    return () =>
+      h(
+        SettingsDialog,
+        {
+          modelValue: props.modelValue,
+          'onUpdate:modelValue': (v: boolean) => emit('update:modelValue', v),
+          tab: active.value,
+          'onUpdate:tab': (v: string) => (active.value = v),
+        },
+        () => [
+          h(SettingsSidebar, () =>
+            h(SettingsNavGroup, { label: 'Workspace' }, () =>
+              tabs.map((tab) =>
+                h(
+                  SettingsNavItem,
+                  { key: tab.value, value: tab.value },
+                  () => tab.label,
+                ),
+              ),
+            ),
+          ),
+          h(SettingsContent, () =>
+            tabs.map((tab) =>
+              h(SettingsPanel, { key: tab.value, value: tab.value }, () =>
+                h(tab.component),
+              ),
+            ),
+          ),
+        ],
+      )
+  },
+})
+
+describe('SettingsDialog', () => {
+  it('does not render while closed; renders when open (v-model)', () => {
+    cy.mount(Harness, { props: { modelValue: false } })
+    cy.get('[role=dialog]').should('not.exist')
+
+    cy.mount(Harness, { props: { modelValue: true } })
+    cy.get('[role=dialog]').should('exist')
+  })
+
+  it('renders all nav items in the sidebar', () => {
+    cy.mount(Harness)
+    cy.get('[role=dialog]').within(() => {
+      cy.contains('Profile').should('exist')
+      cy.contains('General').should('exist')
+      cy.contains('Members').should('exist')
+    })
+  })
+
+  it('shows the first tab content by default', () => {
+    cy.mount(Harness)
+    cy.get('[role=dialog] .tab-panel').should('have.text', 'Profile content')
+  })
+
+  it('switches the active tab on click', () => {
+    cy.mount(Harness)
+    cy.get('[role=dialog] .tab-panel').should('have.text', 'Profile content')
+    cy.get('[role=dialog]').contains('Members').click()
+    cy.get('[role=dialog] .tab-panel').should('have.text', 'Members content')
+  })
+
+  it('exposes tablist / tab / tabpanel roles with aria-selected', () => {
+    cy.mount(Harness)
+    cy.get('[role=tablist]').should('exist')
+    cy.get('[role=tab]').should('have.length', 3)
+    // cy.contains(selector, text) returns the element matching the selector;
+    // a bare .contains() would drill into the inner label <span> instead.
+    cy.contains('[role=tab]', 'Profile').should(
+      'have.attr',
+      'aria-selected',
+      'true',
+    )
+    cy.contains('[role=tab]', 'Members').should(
+      'have.attr',
+      'aria-selected',
+      'false',
+    )
+    cy.get('[role=tabpanel]').should('have.text', 'Profile content')
+  })
+
+  it('moves the active tab with arrow keys (manual activation needs Enter)', () => {
+    cy.mount(Harness)
+    cy.contains('[role=tab]', 'Profile').focus().type('{downarrow}')
+    // manual activation: arrow only moves focus, selection follows on Enter
+    cy.focused().should('contain.text', 'General')
+    cy.focused().type('{enter}')
+    cy.get('[role=tabpanel]').should('have.text', 'General content')
+  })
+
+  it('emits update:modelValue when the dialog is closed', () => {
+    const onUpdate = cy.spy().as('onUpdate')
+    cy.mount(Harness, {
+      props: { modelValue: true, 'onUpdate:modelValue': onUpdate },
+    })
+    cy.get('[role=dialog]').should('exist')
+    cy.get('body').type('{esc}')
+    cy.get('@onUpdate').should('have.been.calledWith', false)
+  })
+})

package/src/components/SettingsDialog/SettingsDialog.md

@@ -0,0 +1,43 @@
+# SettingsDialog
+
+A modal for app settings: a sidebar of grouped tabs on the left, the active
+tab's content on the right. Built on `Dialog`, composed from small building
+blocks rather than a config object.
+
+<ComponentPreview name="SettingsDialog-Default" layout="stacked" />
+
+## Anatomy
+
+It's a [reka-ui Tabs](https://reka-ui.com/docs/components/tabs) set, so you get
+`tablist`/`tab`/`tabpanel` roles, `aria-selected`, and arrow-key focus for free.
+Instead of tracking an `active` flag, give each nav item and panel a matching
+`value`.
+
+- **`SettingsDialog`** — wraps `Dialog`; owns open state (`v-model`), the
+  selected tab (`v-model:tab`), and the `Cmd/Ctrl+Shift+,` shortcut. Full-screen
+  on mobile, centered panel on desktop.
+- **`SettingsSidebar`** / **`SettingsNavGroup`** / **`SettingsNavItem`** — the
+  navigation. Give each item a `:value`; it also takes `#prefix` and `#suffix`.
+- **`SettingsContent`** / **`SettingsPanel`** — the right pane; one panel per
+  tab, each with a `:value` matching its nav item.
+
+`v-model:tab` is optional — bind it to drive selection yourself (Gameplan uses
+it for deep-linkable `/settings/:tab` URLs). Set `:unmount-on-hide="false"` to
+keep visited panels mounted across switches.
+
+## Panels: fixed header, scrolling body
+
+A `SettingsPanel` holds a `SettingsHeader` (pinned) and a `SettingsBody`
+(scrolls), so titles, search inputs, and column headers never scroll away.
+`SettingsHeader` takes `title` + `description` (+ `#actions`), or arbitrary
+content via its default slot.
+
+<ComponentPreview name="SettingsDialog-PanelBasic" />
+
+## SettingsRow
+
+Lays out a setting as label + description on the left, control on the right. A
+slotted frappe-ui control (e.g. `Switch`) is auto-wired to the title `<label>` —
+no `label-for` needed.
+
+<!-- @include: ./SettingsDialog.api.md -->

package/src/components/SettingsDialog/SettingsDialog.vue

@@ -0,0 +1,76 @@
+<template>
+  <Dialog v-model="modelValue" :size="size" bare>
+    <!--
+      TabsRoot wires the sidebar (TabsList) to the panels (TabsContent): roving
+      arrow-key focus, aria-selected/aria-controls, and one visible panel at a
+      time — all from reka-ui. `manual` activation moves focus on arrow keys
+      without selecting until Enter/Space, so a route-driven consumer doesn't
+      navigate on every keypress.
+    -->
+    <TabsRoot
+      v-model="activeTab"
+      orientation="vertical"
+      activation-mode="manual"
+      :unmount-on-hide="unmountOnHide"
+      class="flex h-[100dvh] min-h-0 w-screen flex-col overflow-hidden sm:h-[min(860px,calc(100vh-8rem))] sm:min-h-[560px] sm:w-auto sm:flex-row"
+    >
+      <Dialog.Title as-child>
+        <h1 class="sr-only"><slot name="title">Settings</slot></h1>
+      </Dialog.Title>
+      <Dialog.Description as-child>
+        <p class="sr-only">
+          <slot name="description"
+            >Manage your settings across the tabs in this dialog.</slot
+          >
+        </p>
+      </Dialog.Description>
+      <slot />
+    </TabsRoot>
+  </Dialog>
+</template>
+
+<script setup lang="ts">
+import { useEventListener } from '@vueuse/core'
+import { TabsRoot } from 'reka-ui'
+import { Dialog } from '../Dialog'
+import type { SettingsDialogProps } from './types'
+
+const props = withDefaults(defineProps<SettingsDialogProps>(), {
+  size: '4xl',
+  shortcut: true,
+  unmountOnHide: true,
+})
+
+/** Controls whether the dialog is open. */
+const modelValue = defineModel<boolean>({ default: false })
+
+/**
+ * The selected tab — pairs with SettingsNavItem `:value` and SettingsPanel
+ * `:value`. Optional: leave unbound to let reka-ui manage selection internally,
+ * or bind `v-model:tab` to drive it (e.g. from the route).
+ */
+const activeTab = defineModel<string | number | undefined>('tab')
+
+defineSlots<{
+  /** Accessible dialog title (visually hidden). Defaults to "Settings". */
+  title?: () => any
+  /** Accessible dialog description (visually hidden, for aria-describedby). */
+  description?: () => any
+  /** Sidebar + content panes (compose SettingsSidebar and SettingsContent). */
+  default?: () => any
+}>()
+
+// Cmd/Ctrl+Shift+, toggles the dialog. Use e.code (physical key) since Shift
+// rewrites e.key for "," to "<" on most layouts.
+useEventListener(
+  () => (typeof window === 'undefined' ? null : window),
+  'keydown',
+  (e: KeyboardEvent) => {
+    if (!props.shortcut) return
+    if (e.code === 'Comma' && e.shiftKey && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault()
+      modelValue.value = !modelValue.value
+    }
+  },
+)
+</script>

package/src/components/SettingsDialog/SettingsHeader.vue

@@ -0,0 +1,36 @@
+<template>
+  <!-- Fixed (non-scrolling) header region of a panel. -->
+  <div class="shrink-0 px-[4.4rem] pt-10">
+    <slot>
+      <div class="flex items-start justify-between gap-4">
+        <div class="flex min-w-0 flex-col gap-1">
+          <h2 v-if="title" class="text-lg font-semibold text-ink-gray-8">
+            {{ title }}
+          </h2>
+          <p v-if="description" class="text-base text-ink-gray-6">
+            {{ description }}
+          </p>
+        </div>
+        <div v-if="$slots.actions" class="flex shrink-0 items-center gap-2">
+          <slot name="actions" />
+        </div>
+      </div>
+    </slot>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** Convenience heading. Omit and use the default slot for a custom header. */
+  title?: string
+  /** Optional sub-heading under the title. */
+  description?: string
+}>()
+
+defineSlots<{
+  /** Replaces the entire header (title/description/actions) with custom content. */
+  default?: () => any
+  /** Actions on the right of the default title header. */
+  actions?: () => any
+}>()
+</script>

package/src/components/SettingsDialog/SettingsNavGroup.vue

@@ -0,0 +1,20 @@
+<template>
+  <div>
+    <div
+      v-if="label || $slots.label"
+      class="flex h-7 items-center px-2 text-base text-ink-gray-5"
+    >
+      <slot name="label">{{ label }}</slot>
+    </div>
+    <div class="flex flex-col gap-0.5">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** Group heading shown above its items. */
+  label?: string
+}>()
+</script>

package/src/components/SettingsDialog/SettingsNavItem.vue

@@ -0,0 +1,33 @@
+<template>
+  <!--
+    role="tab". Selected state comes from reka-ui (data-state="active") so the
+    consumer only supplies `:value` — no `active` prop to keep in sync. The gray
+    keyboard focus ring is applied globally via :focus-visible.
+  -->
+  <TabsTrigger
+    :value="value"
+    class="flex h-7 w-full items-center gap-2 rounded px-2 text-left text-base text-ink-gray-7 data-[state=active]:bg-surface-elevation-3 data-[state=active]:shadow-sm data-[state=inactive]:hover:bg-surface-gray-2"
+  >
+    <slot name="prefix" />
+    <span class="min-w-0 flex-1 truncate"><slot /></span>
+    <slot name="suffix" />
+  </TabsTrigger>
+</template>
+
+<script setup lang="ts">
+import { TabsTrigger } from 'reka-ui'
+
+defineProps<{
+  /** Unique tab id — must match the SettingsPanel `value` it controls. */
+  value: string | number
+}>()
+
+defineSlots<{
+  /** Item label. */
+  default?: () => any
+  /** Leading icon or avatar. */
+  prefix?: () => any
+  /** Trailing badge / count. */
+  suffix?: () => any
+}>()
+</script>

package/src/components/SettingsDialog/SettingsPanel.cy.ts

@@ -0,0 +1,77 @@
+import { h } from 'vue'
+import SettingsHeader from './SettingsHeader.vue'
+import SettingsRow from './SettingsRow.vue'
+import Switch from '../Switch/Switch.vue'
+
+describe('SettingsHeader', () => {
+  it('renders the title and description', () => {
+    cy.mount(SettingsHeader, {
+      props: { title: 'General', description: 'Workspace preferences.' },
+    })
+    cy.contains('h2', 'General').should('exist')
+    cy.contains('Workspace preferences.').should('exist')
+  })
+
+  it('omits the description when not provided', () => {
+    cy.mount(SettingsHeader, { props: { title: 'General' } })
+    cy.get('p').should('not.exist')
+  })
+
+  it('renders the actions slot', () => {
+    cy.mount(SettingsHeader, {
+      props: { title: 'General' },
+      slots: { actions: () => h('button', { class: 'action' }, 'Save') },
+    })
+    cy.get('.action').should('have.text', 'Save')
+  })
+
+  it('lets the default slot replace the header entirely', () => {
+    cy.mount(SettingsHeader, {
+      props: { title: 'Ignored' },
+      slots: { default: () => h('div', { class: 'custom' }, 'Custom header') },
+    })
+    cy.get('.custom').should('exist')
+    cy.contains('Ignored').should('not.exist')
+  })
+})
+
+describe('SettingsRow', () => {
+  it('renders the title and description', () => {
+    cy.mount(SettingsRow, {
+      props: { title: 'Public profile', description: 'Allow viewing.' },
+    })
+    cy.contains('Public profile').should('exist')
+    cy.contains('Allow viewing.').should('exist')
+  })
+
+  it('auto-associates the title label with a slotted Switch', () => {
+    cy.mount(SettingsRow, {
+      props: { title: 'Public profile' },
+      slots: { default: () => h(Switch) },
+    })
+    // The title becomes a <label> whose `for` matches the Switch's control id.
+    cy.get('label[for]')
+      .invoke('attr', 'for')
+      .then((forId) => {
+        cy.get(`#${forId}`).should('have.attr', 'data-slot', 'control')
+      })
+  })
+
+  it('toggles the Switch when the auto-wired label is clicked', () => {
+    cy.mount(SettingsRow, {
+      props: { title: 'Public profile' },
+      slots: { default: () => h(Switch) },
+    })
+    cy.get('[data-slot=control]').should('have.attr', 'aria-checked', 'false')
+    cy.get('label[for]').click()
+    cy.get('[data-slot=control]').should('have.attr', 'aria-checked', 'true')
+  })
+
+  it('respects an explicit label-for override', () => {
+    cy.mount(SettingsRow, {
+      props: { title: 'Custom', labelFor: 'my-id' },
+      slots: { default: () => h('input', { id: 'other-id' }) },
+    })
+    cy.get('label').should('have.attr', 'for', 'my-id')
+  })
+})