@svgrid/grid 2.1.6 → 2.1.7

package/src/chart.ts

@@ -106,6 +106,16 @@ export type ChartSpec = {
   height?: number
   /** Palette used when a series has no explicit `color`. */
   palette?: string[]
+  /** Per-category color overrides (by category label) - for pie / donut slice
+   *  recolouring, where colour follows the category, not a series. */
+  categoryColors?: Record<string, string>
+  /** Number format for the value axis, tooltips, data labels and reference
+   *  lines. Unset = the default compact `1.2k` / `1.2M` style. */
+  valueFormat?: ChartValueFormat
+  /** Grouped (nested) category axis: a parent tier spanning consecutive leaf
+   *  categories (spans must sum to `categories.length`). Vertical category
+   *  charts only (ignored for time / horizontal / pie). */
+  categoryGroups?: Array<{ label: string; span: number }>
   /** Stack bar / area series (per axis) instead of grouping them. */
   stacked?: boolean
   /** Stack to 100% (each category normalized to its total). Implies stacked. */
@@ -387,6 +397,9 @@ export type ChartGeometry = {
   y2Ticks: ChartAxisTick[]
   hasRightAxis: boolean
   xTicks: ChartCategoryTick[]
+  /** Grouped category axis parent tier: label + span extent (pixels). Empty
+   *  unless `spec.categoryGroups` is set on a vertical category chart. */
+  categoryGroupTicks: Array<{ label: string; xCenter: number; x0: number; x1: number }>
   /** True when x labels are long/many and should be rotated. */
   xLabelRotated: boolean
   legend: ChartLegendItem[]
@@ -730,6 +743,25 @@ function fmtTick(n: number): string {
   return String(Math.round(n * 100) / 100)
 }
 
+/** Value-axis / tooltip / label number format. */
+export type ChartValueFormat = 'number' | 'currency' | 'percent' | 'compact'
+
+/**
+ * Format a numeric value for display, honouring an optional `valueFormat`.
+ * Builds on the compact `1.2k` / `1.2M` base: currency prefixes `$` (sign
+ * outside), percent multiplies by 100 and suffixes `%`. Unset / `'number'` /
+ * `'compact'` = the plain compact form.
+ */
+export function formatChartValue(n: number, format?: ChartValueFormat): string {
+  if (!Number.isFinite(n)) return ''
+  if (format === 'currency') return `${n < 0 ? '-' : ''}$${fmtTick(Math.abs(n))}`
+  if (format === 'percent') {
+    const p = n * 100
+    return `${Math.round(p * 10) / 10}%`
+  }
+  return fmtTick(n)
+}
+
 const DAY = 86_400_000
 /** Nice date-tick timestamps across [min, max]. */
 function dateTicks(tMin: number, tMax: number): number[] {
@@ -833,6 +865,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     y2Ticks: [],
     hasRightAxis: false,
     xTicks: [],
+    categoryGroupTicks: [],
     xLabelRotated: false,
     legend,
     donut: null,
@@ -945,7 +978,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
       x: round(padL + slotW * i + slotW / 2),
     }))
     const yTicks: ChartAxisTick[] = dom.ticks.map((value) => ({
-      value, y: yOfW(value), label: fmtTick(value),
+      value, y: yOfW(value), label: formatChartValue(value, spec.valueFormat),
     }))
     return {
       ...empty,
@@ -1132,7 +1165,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     const legend = Array.from({ length: 5 }, (_, i) => {
       const t = i / 4
       const value = vMin + (vMax - vMin) * t
-      return { value, color: colorAt(value), label: fmtTick(value) }
+      return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat) }
     })
     return {
       ...empty,
@@ -1486,7 +1519,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     const heatmapLegend = Array.from({ length: 5 }, (_, i) => {
       const t = i / 4
       const value = vMin + (vMax - vMin) * t
-      return { value, color: colorAt(value), label: fmtTick(value) }
+      return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat) }
     })
     return {
       ...empty,
@@ -1537,10 +1570,11 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
       } else {
         path = `M${round(cx)},${round(cy)} L${round(ox0)},${round(oy0)} A${r},${r} 0 ${large} 1 ${round(ox1)},${round(oy1)} Z`
       }
+      const catLabel = spec.categories[i] ?? String(i)
       return {
         path,
-        color: palette[i % palette.length]!,
-        label: spec.categories[i] ?? String(i),
+        color: spec.categoryColors?.[catLabel] ?? palette[i % palette.length]!,
+        label: catLabel,
         value: v,
         percent: frac * 100,
         cx: round(cx + labelR * Math.cos(mid)),
@@ -1550,7 +1584,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     return {
       ...empty,
       slices,
-      legend: spec.categories.map((label, i) => ({ label, color: palette[i % palette.length]! })),
+      legend: spec.categories.map((label, i) => ({ label, color: spec.categoryColors?.[label] ?? palette[i % palette.length]! })),
       donut: ir > 0 ? { cx: round(cx), cy: round(cy), r: round(ir), total: s.values.reduce((a, b) => a + Math.max(0, b), 0) } : null,
     }
   }
@@ -1606,7 +1640,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }
     const referenceLines: ChartRefLineGeo[] = (spec.referenceLines ?? []).map((ref) => ({
       y: yOf(ref.value),
-      label: ref.label ?? fmtTick(ref.value),
+      label: ref.label ?? formatChartValue(ref.value, spec.valueFormat),
       color: ref.color ?? '#ef4444',
       dashed: ref.dashed !== false,
     }))
@@ -1615,7 +1649,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
       plot,
       scatterPoints,
       referenceLines,
-      yTicks: yDom.ticks.map((value) => ({ value, y: yOf(value), label: fmtTick(value) })),
+      yTicks: yDom.ticks.map((value) => ({ value, y: yOf(value), label: formatChartValue(value, spec.valueFormat) })),
       xTicks: xDom.ticks.map((value) => ({ label: fmtTick(value), x: xOf(value) })),
     }
   }
@@ -1702,7 +1736,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }
 
     const valueTicks: ChartCategoryTick[] = dom.ticks.map((value) => ({
-      label: spec.stacked100 ? `${fmtTick(value)}%` : fmtTick(value),
+      label: spec.stacked100 ? `${fmtTick(value)}%` : formatChartValue(value, spec.valueFormat),
       x: xOf(value),
     }))
     const catTicks: ChartAxisTick[] = spec.categories.map((label, i) => ({
@@ -1712,7 +1746,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     }))
     const referenceLinesV: ChartRefLineGeoV[] = (spec.referenceLines ?? []).map((ref) => ({
       x: xOf(ref.value),
-      label: ref.label ?? fmtTick(ref.value),
+      label: ref.label ?? formatChartValue(ref.value, spec.valueFormat),
       color: ref.color ?? '#ef4444',
       dashed: ref.dashed !== false,
     }))
@@ -1736,10 +1770,20 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
 
   const maxLabel = spec.categories.reduce((m, c) => Math.max(m, c.length), 0)
   const xLabelRotated = spec.categories.length > 8 || maxLabel > 9
+  // Grouped (nested) category axis: valid only when the spans cover every leaf.
+  const validGroups =
+    spec.categoryGroups &&
+    spec.categoryGroups.length > 0 &&
+    spec.xType !== 'time' &&
+    spec.orientation !== 'horizontal' &&
+    spec.categoryGroups.reduce((a, g) => a + g.span, 0) === spec.categories.length
+      ? spec.categoryGroups
+      : null
+  const groupTierH = validGroups ? 18 : 0
   const padL = 48 + (spec.yAxisTitle ? 16 : 0)
   const padR = (hasRightAxis ? 48 : 12) + (spec.y2AxisTitle ? 16 : 0)
   const padT = 10
-  const padB = (xLabelRotated ? 54 : 28) + (spec.xAxisTitle ? 16 : 0)
+  const padB = (xLabelRotated ? 54 : 28) + (spec.xAxisTitle ? 16 : 0) + groupTierH
   const plotW = Math.max(1, width - padL - padR)
   const plotH = Math.max(1, height - padT - padB)
   const plot = { x: padL, y: padT, w: plotW, h: plotH }
@@ -1790,6 +1834,18 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
       }))
     : spec.categories.map((label, i) => ({ label, x: xCenter(i) }))
 
+  // Parent-tier ticks for a grouped category axis: each spans its leaves.
+  const categoryGroupTicks: ChartGeometry['categoryGroupTicks'] = []
+  if (validGroups && !timeOk) {
+    let start = 0
+    for (const g of validGroups) {
+      const x0 = round(padL + slot * start)
+      const x1 = round(padL + slot * (start + g.span))
+      categoryGroupTicks.push({ label: g.label, x0, x1, xCenter: round((x0 + x1) / 2) })
+      start += g.span
+    }
+  }
+
   const barSeries = series.filter((s) => s.kind === 'bar')
   const bars: ChartBar[] = []
   if (barSeries.length) {
@@ -1992,7 +2048,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
   }
 
   const tickFor = (dom: NiceScale, log: boolean): ChartAxisTick[] =>
-    dom.ticks.map((value) => ({ value, y: yOf(dom, value, log), label: fmtTick(value) }))
+    dom.ticks.map((value) => ({ value, y: yOf(dom, value, log), label: formatChartValue(value, spec.valueFormat) }))
 
   const referenceLines: ChartRefLineGeo[] = (spec.referenceLines ?? []).map((ref) => {
     const onRight = ref.axis === 'right'
@@ -2000,7 +2056,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     const log = onRight ? rightLog : leftLog
     return {
       y: yOf(dom, ref.value, log),
-      label: ref.label ?? fmtTick(ref.value),
+      label: ref.label ?? formatChartValue(ref.value, spec.valueFormat),
       color: ref.color ?? '#ef4444',
       dashed: ref.dashed !== false,
     }
@@ -2081,6 +2137,7 @@ export function buildChart(spec: ChartSpec, theme: 'light' | 'dark' = 'light'):
     y2Ticks: rightDom ? tickFor(rightDom, rightLog) : [],
     hasRightAxis,
     xTicks,
+    categoryGroupTicks,
     xLabelRotated: timeOk ? false : xLabelRotated,
     referenceLines,
     overlays,

package/src/createAutocomplete.svelte.ts

@@ -41,7 +41,12 @@ export type AutocompleteConfig = {
   hint?: () => string | undefined
 }
 
+let uid = 0
+
 export function createAutocomplete(config: AutocompleteConfig) {
+  const id = `sv-ac-${uid++}`
+  const listId = `${id}-list`
+  const optionId = (index: number) => `${listId}-opt-${index}`
   const minChars = () => config.minChars?.() ?? 1
 
   const ariaState = (): EditorAriaState => ({
@@ -82,6 +87,8 @@ export function createAutocomplete(config: AutocompleteConfig) {
     get filtered() { return filtered },
     /** Controlled text value. */
     get value() { return config.value() },
+    /** id of the listbox element (matches inputProps `aria-controls`). */
+    listId,
     isActive: (i: number) => i === active,
     setActive: (i: number) => { active = i },
     maybeOpen,
@@ -94,7 +101,9 @@ export function createAutocomplete(config: AutocompleteConfig) {
       id: config.id?.(),
       role: 'combobox' as const,
       'aria-expanded': open,
+      'aria-controls': listId,
       'aria-autocomplete': 'list' as const,
+      'aria-activedescendant': open && filtered[active] ? optionId(active) : undefined,
       ...editorAria(ariaState()),
       value: config.value(),
       disabled: config.disabled?.() ?? false,
@@ -104,10 +113,12 @@ export function createAutocomplete(config: AutocompleteConfig) {
     }),
     /** Spread onto the listbox container. */
     listboxProps: () => ({
+      id: listId,
       role: 'listbox' as const,
     }),
     /** Spread onto the suggestion at `index` (index into `filtered`). */
     optionProps: (index: number) => ({
+      id: optionId(index),
       role: 'option' as const,
       tabindex: -1,
       'aria-selected': index === active,

package/src/createCombobox.svelte.ts

@@ -138,6 +138,7 @@ export function createCombobox(config: ComboboxConfig) {
       'aria-expanded': open,
       'aria-controls': listId,
       'aria-autocomplete': 'list' as const,
+      'aria-activedescendant': open && filtered[active] ? optionId(active) : undefined,
       ...editorAria(ariaState()),
       value: shownText,
       disabled: disabled(),

package/src/createCountryInput.svelte.ts

@@ -41,7 +41,12 @@ export type CountryInputConfig = {
   hint?: () => string | undefined
 }
 
+let uid = 0
+
 export function createCountryInput(config: CountryInputConfig) {
+  const id = `sv-country-${uid++}`
+  const listId = `${id}-list`
+  const optionId = (i: number) => `${listId}-opt-${i}`
   const disabled = () => config.disabled?.() ?? false
 
   const ariaState = (): EditorAriaState => ({
@@ -75,6 +80,8 @@ export function createCountryInput(config: CountryInputConfig) {
   function pick(code: string) { config.onChange?.(code); open = false; config.focusTrigger?.() }
   function setQuery(v: string) { query = v; active = 0 }
   function onSearchInput(e: Event) { setQuery((e.currentTarget as HTMLInputElement).value) }
+  /** The current active-descendant id (for the focused search input), or undefined. */
+  const activeDescendant = () => (open && filtered.length > 0 ? optionId(active) : undefined)
   function onKeydown(e: KeyboardEvent) {
     if (!open) return
     if (e.key === 'ArrowDown') { e.preventDefault(); active = Math.min(active + 1, filtered.length - 1) }
@@ -111,6 +118,7 @@ export function createCountryInput(config: CountryInputConfig) {
       type: 'button' as const,
       'aria-haspopup': 'listbox' as const,
       'aria-expanded': open,
+      'aria-controls': listId,
       ...editorAria(ariaState()),
       disabled: disabled(),
       onclick: toggle,
@@ -120,17 +128,21 @@ export function createCountryInput(config: CountryInputConfig) {
       type: 'text' as const,
       value: query,
       'aria-label': config.searchLabel?.() ?? 'Search countries',
+      'aria-controls': listId,
+      'aria-activedescendant': activeDescendant(),
       oninput: onSearchInput,
       onkeydown: onKeydown,
     }),
     /** Spread onto the listbox container. */
     listboxProps: () => ({
+      id: listId,
       role: 'listbox' as const,
     }),
     /** Spread onto the country option at `index` (index into `filtered`). */
     optionProps: (index: number) => {
       const c = filtered[index]
       return {
+        id: optionId(index),
         role: 'option' as const,
         tabindex: -1,
         'aria-selected': c ? c.code === config.value() : false,

package/src/createDropdownList.svelte.ts

@@ -41,7 +41,11 @@ export type DropdownListConfig = {
   hint?: () => string | undefined
 }
 
+let uid = 0
+
 export function createDropdownList(config: DropdownListConfig) {
+  const listId = `sv-ddl-${uid++}`
+  const optionId = (index: number) => `${listId}-opt-${index}`
   const opts = () => config.options()
   const disabled = () => config.disabled?.() ?? false
 
@@ -125,6 +129,8 @@ export function createDropdownList(config: DropdownListConfig) {
       type: 'button' as const,
       'aria-haspopup': 'listbox' as const,
       'aria-expanded': open,
+      'aria-controls': listId,
+      'aria-activedescendant': open && opts()[active] ? optionId(active) : undefined,
       ...editorAria(ariaState()),
       disabled: disabled(),
       onclick: toggle,
@@ -132,6 +138,7 @@ export function createDropdownList(config: DropdownListConfig) {
     }),
     /** Spread onto the listbox container. */
     listboxProps: () => ({
+      id: listId,
       role: 'listbox' as const,
       tabindex: -1,
     }),
@@ -140,6 +147,7 @@ export function createDropdownList(config: DropdownListConfig) {
       const o = opts()[index]
       return {
         role: 'option' as const,
+        id: optionId(index),
         tabindex: -1,
         'aria-selected': o ? o.value === config.value() : false,
         'aria-disabled': o?.disabled,

package/src/createPopoverSelect.svelte.ts

@@ -182,9 +182,11 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
     onPanelKeydown,
     /** True when item `i` is the roving-active one. */
     isActive: (i: number) => i === active,
-    /** Spread onto the trigger button. */
-    triggerProps: () => ({
-      'aria-haspopup': 'listbox' as const,
+    /** Spread onto the trigger button. Pass the ARIA popup type the panel
+     *  exposes (mirrors `focusOwnerProps(role)`); defaults to 'listbox' for
+     *  the classic select panels. */
+    triggerProps: (haspopup: 'listbox' | 'tree' | 'grid' = 'listbox') => ({
+      'aria-haspopup': haspopup,
       'aria-expanded': open,
       'aria-controls': open ? panelId : undefined,
       onkeydown: onTriggerKeydown,

package/src/createTree.svelte.ts

@@ -231,6 +231,18 @@ export function createTree(config: TreeConfig) {
     config.onCheck?.([...next])
   }
 
+  // Step from `from` towards `dir` (+1/-1), skipping disabled rows, so roving
+  // focus never lands on a node with zero semantic affordance for AT users.
+  // Falls back to `from` if every row in that direction is disabled.
+  function stepEnabled(from: number, dir: 1 | -1): number {
+    let i = from
+    while (i + dir >= 0 && i + dir <= rows.length - 1) {
+      i += dir
+      if (!rows[i]?.node.disabled) return i
+    }
+    return from
+  }
+
   function onKeydown(e: KeyboardEvent) {
     const item = rows[active]
     if (!item) return
@@ -246,8 +258,8 @@ export function createTree(config: TreeConfig) {
     }
     const rtl = config.dir?.() === 'rtl'
     switch (e.key) {
-      case 'ArrowDown': e.preventDefault(); setActive(Math.min(active + 1, rows.length - 1), true); break
-      case 'ArrowUp': e.preventDefault(); setActive(Math.max(active - 1, 0), true); break
+      case 'ArrowDown': e.preventDefault(); setActive(stepEnabled(active, 1), true); break
+      case 'ArrowUp': e.preventDefault(); setActive(stepEnabled(active, -1), true); break
       case 'ArrowRight': e.preventDefault(); (rtl ? collapse : expand)(); break
       case 'ArrowLeft': e.preventDefault(); (rtl ? expand : collapse)(); break
       case 'Enter': e.preventDefault(); select(item.node); break
@@ -294,6 +306,7 @@ export function createTree(config: TreeConfig) {
         'aria-selected': row.node.id === selected(),
         'aria-expanded': row.hasChildren ? row.open : undefined,
         'aria-checked': ariaChecked,
+        'aria-disabled': row.node.disabled || undefined,
         'data-row': row.index,
         tabindex: row.index === active ? 0 : -1,
         onclick: () => { setActive(row.index); select(row.node) },

package/src/index.ts

@@ -286,8 +286,11 @@ export {
 export { default as FlexRender } from './FlexRender.svelte'
 export { renderComponent, renderSnippet } from './render-component'
 export { default as SvGridChart } from './SvGridChart.svelte'
+export { default as SvGridChartPanel } from './SvGridChartPanel.svelte'
+export type { ChartingConfig, ChartAggregateRequest, ChartAggregateBucket } from './SvGrid.types'
 export {
   buildChart,
+  formatChartValue,
   rowsToChartSpec,
   niceScale,
   niceLogScale,
@@ -326,6 +329,7 @@ export {
   type ChartGaugeLayout,
   type ChartSankeyNode,
   type ChartSankeyLink,
+  type ChartValueFormat,
   type TreeNode,
 } from './chart'
 export {
@@ -333,6 +337,8 @@ export {
   downloadChartSvg,
   chartToPngBlob,
   downloadChartPng,
+  chartSpecToCsv,
+  downloadChartCsv,
   type ChartExportOptions,
 } from './chart-export'
 export {

package/src/overlays.test.ts

@@ -79,6 +79,11 @@ describe('SvTooltip', () => {
       expect(tip).not.toBeNull()
       expect(tip.getAttribute('role')).toBe('tooltip')
       expect(anchor.getAttribute('aria-describedby')).toBe(tip.id)
+      // The wrapper span is never itself focusable, so AT users only ever land
+      // on the real interactive child below - it must carry the description
+      // too, or it's never announced on focus (see SvTooltip.svelte effect).
+      const focusEl = target.querySelector<HTMLElement>('.t')!
+      expect(focusEl.getAttribute('aria-describedby')).toBe(tip.id)
       destroy()
     } finally { vi.useRealTimers() }
   })

package/src/svgrid-wrapper.types.ts

@@ -1,5 +1,6 @@
 import type { CellFormatConfig, ColumnDef, RowData, SvGridOptions, TableFeatures } from './core'
 import type { GridExportOptions, GridClipboardOptions } from './export-format'
+import type { ChartSpec, ChartType } from './chart'
 
 export type SvGridFilterOperator =
   | 'contains'
@@ -33,6 +34,32 @@ export type SvGridViewState = {
   >
   /** Facet (Excel-style value checklist) selections, keyed by column id. */
   facetFilters: Record<string, string[]>
+  /** Built-in chart panel state (present only when `charting` is on): the
+   *  ACTIVE chart, for back-compat + spread-and-tweak. */
+  chart?: {
+    open: boolean
+    type: ChartType
+    dimension: string | null
+    series: string | null
+    measure: string | null
+    reduce: 'sum' | 'avg' | 'count'
+    stacked: boolean
+  }
+  /** All charts in the tab strip (multi-chart), plus the active index. */
+  charts?: Array<{
+    title: string
+    type: ChartType
+    dimension: string | null
+    series: string | null
+    measure: string | null
+    reduce: 'sum' | 'avg' | 'count'
+    stacked: boolean | null
+    dataLabels: boolean | null
+    logScale: boolean | null
+    timeAxis: boolean | null
+    valueFormat: 'number' | 'currency' | 'percent' | 'compact' | null
+  }>
+  chartActive?: number
 }
 
 /**
@@ -94,6 +121,41 @@ export type SvGridApi<
    */
   getSelected(): Array<[number, number, number, number]>
 
+  // ----- Integrated charting (requires the `charting` prop) -----
+  /** Open the built-in chart panel. */
+  openChart(): void
+  /** Close the built-in chart panel. */
+  closeChart(): void
+  /** The live chart spec the panel is rendering, or `null`. */
+  getChartSpec(): ChartSpec | null
+  /** Select cell rectangles + open the chart panel (scopes to the range). */
+  chartRange(ranges?: ReadonlyArray<readonly [number, number, number, number]>): void
+  /**
+   * Configure the built-in chart panel's ACTIVE chart. Column references
+   * accept a column id OR field name. Opens the panel unless `open === false`.
+   */
+  configureChart(config: {
+    open?: boolean
+    type?: ChartType
+    dimension?: string | null
+    series?: string | null
+    measure?: string | null
+    reduce?: 'sum' | 'avg' | 'count'
+    stacked?: boolean
+    dataLabels?: boolean
+    logScale?: boolean
+    timeAxis?: boolean
+    valueFormat?: 'number' | 'currency' | 'percent' | 'compact'
+  }): void
+  /**
+   * Register a natural-language "chart this" handler. When set, the chart
+   * panel shows an AI button. `@svgrid/enterprise`'s `enableAiCharting(api)`
+   * fills this. Pass `null` to remove it.
+   */
+  setChartAiHandler(
+    handler: ((prompt: string) => Promise<Record<string, unknown> | null>) | null,
+  ): void
+
   // ----- Rows -----
   /** Add one row. `position` defaults to `'bottom'`. */
   addRow(row: TData, position?: 'top' | 'bottom' | number): void