@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroSidebar/FuroSidebarContext.js

@@ -0,0 +1,1014 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+const DEFAULT_NAVIGATION_LABEL = 'Sidebar'
+const DEFAULT_SEARCH_LABEL = 'Search'
+
+/**
+ * Context class for FuroSidebar organism.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroSidebarContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroSidebarContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroSidebarContext ? X : never} T, X
+   * @override
+   * @param {FuroSidebarContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    refHash = this.buildRefHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        refHash,
+      })
+    )
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @override
+   * @returns {FuroSidebarContextParams['refHash']} Ref hash.
+   */
+  static buildRefHash () {
+    return {
+      activeKeyRef: /** @type {import('vue').Ref<string | null>} */ (ref(null)),
+      expandedKeysRef: /** @type {import('vue').Ref<Array<string>>} */ (ref([])),
+    }
+  }
+
+  /**
+   * Icon marking an open disclosure.
+   *
+   * @returns {string} Name of a built-in icon.
+   */
+  static get OPEN_DISCLOSURE_ICON_NAME () {
+    return 'ph:caret-up'
+  }
+
+  /**
+   * Icon marking a closed disclosure.
+   *
+   * @returns {string} Name of a built-in icon.
+   */
+  static get CLOSED_DISCLOSURE_ICON_NAME () {
+    return 'ph:caret-down'
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   NAVIGATE: 'navigate'
+   *   UPDATE_ACTIVE_KEY: 'update:activeKey'
+   *   EXPAND_CHANGE: 'expand-change'
+   *   UPDATE_EXPANDED_KEYS: 'update:expandedKeys'
+   *   SEARCH_CHANGE: 'search-change'
+   *   SEARCH_COMMIT: 'search-commit'
+   *   UPDATE_SEARCH_VALUE: 'update:searchValue'
+   * }>} Emit event names.
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      NAVIGATE: 'navigate',
+      UPDATE_ACTIVE_KEY: 'update:activeKey',
+      EXPAND_CHANGE: 'expand-change',
+      UPDATE_EXPANDED_KEYS: 'update:expandedKeys',
+      SEARCH_CHANGE: 'search-change',
+      SEARCH_COMMIT: 'search-commit',
+      UPDATE_SEARCH_VALUE: 'update:searchValue',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'navigate': (payload: NavigatePayload) => boolean
+   *   'update:activeKey': (key: string) => boolean
+   *   'expand-change': (payload: ExpandChangePayload) => boolean
+   *   'update:expandedKeys': (keys: Array<string>) => boolean
+   *   'search-change': (payload: SidebarSearchPayload) => boolean
+   *   'search-commit': (payload: SidebarSearchPayload) => boolean
+   *   'update:searchValue': (value: string | null) => boolean
+   * }} Emit event hash.
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.NAVIGATE]: (/** @type {NavigatePayload} */ payload) => true,
+      [this.EMIT_EVENT_NAME.UPDATE_ACTIVE_KEY]: (/** @type {string} */ key) => true,
+      [this.EMIT_EVENT_NAME.EXPAND_CHANGE]: (/** @type {ExpandChangePayload} */ payload) => true,
+      [this.EMIT_EVENT_NAME.UPDATE_EXPANDED_KEYS]: (/** @type {Array<string>} */ keys) => true,
+      [this.EMIT_EVENT_NAME.SEARCH_CHANGE]: (/** @type {SidebarSearchPayload} */ payload) => true,
+      [this.EMIT_EVENT_NAME.SEARCH_COMMIT]: (/** @type {SidebarSearchPayload} */ payload) => true,
+      [this.EMIT_EVENT_NAME.UPDATE_SEARCH_VALUE]: (/** @type {string | null} */ value) => true,
+    }
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroSidebarContext} Constructor of this class.
+   */
+  get Ctor () {
+    return /** @type {typeof FuroSidebarContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * get: the internally held active key, used while uncontrolled.
+   *
+   * @returns {import('vue').Ref<string | null>} Ref of the active key.
+   */
+  get activeKeyRef () {
+    return this.refHash.activeKeyRef
+  }
+
+  /**
+   * get: the internally held open disclosures, used while uncontrolled.
+   *
+   * @returns {import('vue').Ref<Array<string>>} Ref of the open keys.
+   */
+  get expandedKeysRef () {
+    return this.refHash.expandedKeysRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {NonNullable<Props['parcel']>} Parcel filled with its defaults.
+   */
+  get parcel () {
+    return {
+      groups: [],
+      collapsed: false,
+      searchable: false,
+      searchValue: null,
+      searchPlaceholder: null,
+      searchLabel: DEFAULT_SEARCH_LABEL,
+      label: DEFAULT_NAVIGATION_LABEL,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Normalized groups for rendering.
+   *
+   * @returns {Array<GroupEntry>} Group entries.
+   */
+  get groupEntries () {
+    return (this.parcel?.groups ?? [])
+      .map(it => ({
+        key: it.key,
+        label: it.label ?? null,
+        items: this.buildItemEntries({
+          items: it.items ?? [],
+        }),
+      }))
+  }
+
+  /**
+   * Whether the rail is drawn as the narrow icon-only form.
+   *
+   * @returns {boolean} Whether the rail is collapsed.
+   */
+  isCollapsed () {
+    return this.parcel?.collapsed === true
+  }
+
+  /**
+   * Whether the active key arrives from the parcel rather than from within.
+   *
+   * @returns {boolean} Whether the active key is controlled.
+   */
+  isControlledActiveKey () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'activeKey')
+  }
+
+  /**
+   * Whether the open disclosures arrive from the parcel rather than from within.
+   *
+   * @returns {boolean} Whether the open disclosures are controlled.
+   */
+  isControlledExpandedKeys () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'expandedKeys')
+  }
+
+  /**
+   * Whether a given key is the one the application currently shows.
+   *
+   * @param {{
+   *   key: string
+   * }} params - Parameters.
+   * @returns {boolean} Whether the key is active.
+   */
+  isActiveEntry ({
+    key,
+  }) {
+    return this.extractActiveKey() === key
+  }
+
+  /**
+   * Whether a given key has its sub-items revealed.
+   *
+   * @param {{
+   *   key: string
+   * }} params - Parameters.
+   * @returns {boolean} Whether the disclosure is open.
+   */
+  isExpandedEntry ({
+    key,
+  }) {
+    return this.extractExpandedKeys()
+      .includes(key)
+  }
+
+  /**
+   * Whether the header region renders.
+   *
+   * @returns {boolean} Whether the header slot was filled.
+   */
+  hasHeaderSlot () {
+    return Boolean(this.slots?.header)
+  }
+
+  /**
+   * Whether the footer region renders.
+   *
+   * @returns {boolean} Whether the footer slot was filled.
+   */
+  hasFooterSlot () {
+    return Boolean(this.slots?.footer)
+  }
+
+  /**
+   * Whether the search entry renders.
+   *
+   * A collapsed rail is one icon box wide, which no text control fits in, so the
+   * entry is dropped there rather than squeezed.
+   *
+   * @returns {boolean} Whether the search entry renders.
+   */
+  shouldShowSearch () {
+    return this.parcel?.searchable === true
+      && !this.isCollapsed()
+  }
+
+  /**
+   * Whether a group draws its heading.
+   *
+   * @param {{
+   *   group: GroupEntry
+   * }} params - Parameters.
+   * @returns {boolean} Whether the heading renders.
+   */
+  shouldShowGroupLabel ({
+    group,
+  }) {
+    return group.label !== null
+      && !this.isCollapsed()
+  }
+
+  /**
+   * Whether item labels render.
+   *
+   * @returns {boolean} Whether labels render.
+   */
+  shouldShowLabel () {
+    return !this.isCollapsed()
+  }
+
+  /**
+   * Whether an item draws its disclosure caret.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {boolean} Whether the caret renders.
+   */
+  shouldShowDisclosureIcon ({
+    entry,
+  }) {
+    return entry.hasSubItems
+      && !this.isCollapsed()
+  }
+
+  /**
+   * Whether an item reveals its sub-items.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {boolean} Whether the sub-items render.
+   */
+  shouldShowSubItems ({
+    entry,
+  }) {
+    return entry.hasSubItems
+      && this.isExpandedEntry({
+        key: entry.key,
+      })
+      && !this.isCollapsed()
+  }
+
+  /**
+   * Resolve the key the application currently shows.
+   *
+   * @returns {string | null} The active key.
+   */
+  extractActiveKey () {
+    if (this.isControlledActiveKey()) {
+      return this.parcel?.activeKey
+        ?? null
+    }
+
+    return this.activeKeyRef.value
+  }
+
+  /**
+   * Resolve the keys whose sub-items are revealed.
+   *
+   * @returns {Array<string>} The open keys.
+   */
+  extractExpandedKeys () {
+    if (this.isControlledExpandedKeys()) {
+      return this.parcel?.expandedKeys
+        ?? []
+    }
+
+    return this.expandedKeysRef.value
+  }
+
+  /**
+   * Resolve the caret an item draws.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {string} Name of a built-in icon.
+   */
+  extractDisclosureIconName ({
+    entry,
+  }) {
+    return this.isExpandedEntry({
+      key: entry.key,
+    })
+      ? this.Ctor.OPEN_DISCLOSURE_ICON_NAME
+      : this.Ctor.CLOSED_DISCLOSURE_ICON_NAME
+  }
+
+  /**
+   * Resolve the name a collapsed item is announced and titled with.
+   *
+   * An expanded rail shows the label as text, so repeating it as an attribute
+   * would have a screen reader read it twice.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {string | null} The label, or null while the rail is expanded.
+   */
+  extractCollapsedItemLabel ({
+    entry,
+  }) {
+    return this.isCollapsed()
+      ? entry.label
+      : null
+  }
+
+  /**
+   * Resolve the aria-current value of an item.
+   *
+   * @param {{
+   *   entry: ItemEntry | SubItemEntry
+   * }} params - Parameters.
+   * @returns {'page' | null} The aria-current value.
+   */
+  extractCurrentValue ({
+    entry,
+  }) {
+    return this.isActiveEntry({
+      key: entry.key,
+    })
+      ? 'page'
+      : null
+  }
+
+  /**
+   * Resolve the aria-expanded value of an item.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {'true' | 'false' | null} The aria-expanded value, null when the item discloses nothing.
+   */
+  extractDisclosureExpandedValue ({
+    entry,
+  }) {
+    if (!entry.hasSubItems) {
+      return null
+    }
+
+    return this.isExpandedEntry({
+      key: entry.key,
+    })
+      ? 'true'
+      : 'false'
+  }
+
+  /**
+   * Resolve the accessible name of the navigation landmark.
+   *
+   * @returns {string} Name of the landmark.
+   */
+  extractNavigationLabel () {
+    return this.parcel?.label
+      ?? DEFAULT_NAVIGATION_LABEL
+  }
+
+  /**
+   * Resolve the placeholder of the search control.
+   *
+   * @returns {string | null} Placeholder of the search control.
+   */
+  extractSearchPlaceholder () {
+    return this.parcel?.searchPlaceholder
+      ?? null
+  }
+
+  /**
+   * Resolve the accessible name of the search control.
+   *
+   * @returns {string} Name of the search control.
+   */
+  extractSearchLabel () {
+    return this.parcel?.searchLabel
+      ?? DEFAULT_SEARCH_LABEL
+  }
+
+  /**
+   * Resolve the text the search control holds.
+   *
+   * @returns {string | null} The search text.
+   */
+  extractSearchValue () {
+    return this.parcel?.searchValue
+      ?? null
+  }
+
+  /**
+   * Extract attributes handed to the search control.
+   *
+   * @returns {{
+   *   placeholder: string | null
+   *   'aria-label': string
+   * }} Attributes of the search control.
+   */
+  extractSearchAttributes () {
+    return {
+      placeholder: this.extractSearchPlaceholder(),
+      'aria-label': this.extractSearchLabel(),
+    }
+  }
+
+  /**
+   * Extract CSS class map for the root.
+   *
+   * @returns {Record<string, boolean>} Class map of the root.
+   */
+  extractRootClassNames () {
+    return {
+      'unit-sidebar': true,
+      collapsed: this.isCollapsed(),
+    }
+  }
+
+  /**
+   * Extract CSS class map for a primary item.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {Record<string, boolean>} Class map of the item.
+   */
+  extractItemClassNames ({
+    entry,
+  }) {
+    return {
+      row: true,
+      active: this.isActiveEntry({
+        key: entry.key,
+      }),
+      disclosure: entry.hasSubItems,
+    }
+  }
+
+  /**
+   * Extract CSS class map for a nested sub-item.
+   *
+   * @param {{
+   *   entry: SubItemEntry
+   * }} params - Parameters.
+   * @returns {Record<string, boolean>} Class map of the sub-item.
+   */
+  extractSubItemClassNames ({
+    entry,
+  }) {
+    return {
+      'sub-row': true,
+      active: this.isActiveEntry({
+        key: entry.key,
+      }),
+    }
+  }
+
+  /**
+   * Build the entries of one group.
+   *
+   * @param {{
+   *   items: Array<FuroSidebarItem>
+   * }} params - Parameters.
+   * @returns {Array<ItemEntry>} Item entries.
+   */
+  buildItemEntries ({
+    items,
+  }) {
+    return items.map(it => ({
+      key: it.key,
+      label: it.label,
+      icon: it.icon ?? null,
+      hasIcon: Boolean(it.icon),
+      disabled: Boolean(it.disabled),
+      subItems: this.buildSubItemEntries({
+        items: it.items ?? [],
+      }),
+      hasSubItems: (it.items ?? []).length > 0,
+    }))
+  }
+
+  /**
+   * Build the entries nested under one item.
+   *
+   * @param {{
+   *   items: Array<FuroSidebarSubItem>
+   * }} params - Parameters.
+   * @returns {Array<SubItemEntry>} Sub-item entries.
+   */
+  buildSubItemEntries ({
+    items,
+  }) {
+    return items.map(it => ({
+      key: it.key,
+      label: it.label,
+      disabled: Boolean(it.disabled),
+    }))
+  }
+
+  /**
+   * Build attributes of the root host element.
+   *
+   * @param {{
+   *   attrs: Record<string, *>
+   * }} params - Parameters.
+   * @returns {Record<string, *>} Attributes of the root.
+   */
+  buildRootAttributes ({
+    attrs,
+  }) {
+    return {
+      'aria-label': this.extractNavigationLabel(),
+      ...attrs,
+    }
+  }
+
+  /**
+   * Build attributes of a primary item.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   * @returns {{
+   *   disabled: boolean
+   *   title: string | null
+   *   'aria-label': string | null
+   *   'aria-current': 'page' | null
+   *   'aria-expanded': 'true' | 'false' | null
+   * }} Attributes of the item.
+   */
+  buildItemAttributes ({
+    entry,
+  }) {
+    const collapsedLabel = this.extractCollapsedItemLabel({
+      entry,
+    })
+
+    return {
+      disabled: entry.disabled,
+      title: collapsedLabel,
+      'aria-label': collapsedLabel,
+      'aria-current': this.extractCurrentValue({
+        entry,
+      }),
+      'aria-expanded': this.extractDisclosureExpandedValue({
+        entry,
+      }),
+    }
+  }
+
+  /**
+   * Build attributes of a nested sub-item.
+   *
+   * @param {{
+   *   entry: SubItemEntry
+   * }} params - Parameters.
+   * @returns {{
+   *   disabled: boolean
+   *   'aria-current': 'page' | null
+   * }} Attributes of the sub-item.
+   */
+  buildSubItemAttributes ({
+    entry,
+  }) {
+    return {
+      disabled: entry.disabled,
+      'aria-current': this.extractCurrentValue({
+        entry,
+      }),
+    }
+  }
+
+  /**
+   * Build the parcel handed to the search control.
+   *
+   * @returns {{
+   *   value: string | null
+   * }} Parcel of the search control.
+   */
+  buildSearchParcel () {
+    return {
+      value: this.extractSearchValue(),
+    }
+  }
+
+  /**
+   * Build the open keys a disclosure toggle results in.
+   *
+   * @param {{
+   *   key: string
+   * }} params - Parameters.
+   * @returns {Array<string>} The next open keys.
+   */
+  buildNextExpandedKeys ({
+    key,
+  }) {
+    const currentKeys = this.extractExpandedKeys()
+    const remainingKeys = currentKeys.filter(it => it !== key)
+
+    return remainingKeys.length === currentKeys.length
+      ? [
+        ...currentKeys,
+        key,
+      ]
+      : remainingKeys
+  }
+
+  /**
+   * Handle a click on a primary item.
+   *
+   * An item that discloses sub-items opens and closes them; the design gives it
+   * a caret rather than a destination, so it never reports navigation.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   */
+  onActivateEntry ({
+    entry,
+  }) {
+    if (entry.hasSubItems) {
+      this.toggleDisclosure({
+        entry,
+      })
+
+      return
+    }
+
+    this.selectKey({
+      key: entry.key,
+      parentKey: null,
+    })
+  }
+
+  /**
+   * Handle a click on a nested sub-item.
+   *
+   * @param {{
+   *   entry: SubItemEntry
+   *   parentEntry: ItemEntry
+   * }} params - Parameters.
+   */
+  onActivateSubEntry ({
+    entry,
+    parentEntry,
+  }) {
+    this.selectKey({
+      key: entry.key,
+      parentKey: parentEntry.key,
+    })
+  }
+
+  /**
+   * Handle a keystroke reported by the search control.
+   *
+   * @param {{
+   *   payload: SidebarSearchPayload
+   * }} params - Parameters.
+   */
+  onSearchChange ({
+    payload,
+  }) {
+    this.emit(
+      this.EMIT_EVENT_NAME.SEARCH_CHANGE,
+      payload
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_SEARCH_VALUE,
+      payload.value
+    )
+  }
+
+  /**
+   * Handle a settled value reported by the search control.
+   *
+   * @param {{
+   *   payload: SidebarSearchPayload
+   * }} params - Parameters.
+   */
+  onSearchCommit ({
+    payload,
+  }) {
+    this.emit(
+      this.EMIT_EVENT_NAME.SEARCH_COMMIT,
+      payload
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_SEARCH_VALUE,
+      payload.value
+    )
+  }
+
+  /**
+   * Report that a key is the one the application should show.
+   *
+   * @param {{
+   *   key: string
+   *   parentKey: string | null
+   * }} params - Parameters.
+   */
+  selectKey ({
+    key,
+    parentKey,
+  }) {
+    if (!this.isControlledActiveKey()) {
+      this.activeKeyRef.value = key
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_ACTIVE_KEY,
+      key
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.NAVIGATE,
+      {
+        key,
+        parentKey,
+      }
+    )
+  }
+
+  /**
+   * Open or close the sub-items of one item.
+   *
+   * @param {{
+   *   entry: ItemEntry
+   * }} params - Parameters.
+   */
+  toggleDisclosure ({
+    entry,
+  }) {
+    const expandedKeys = this.buildNextExpandedKeys({
+      key: entry.key,
+    })
+
+    if (!this.isControlledExpandedKeys()) {
+      this.expandedKeysRef.value = expandedKeys
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_EXPANDED_KEYS,
+      expandedKeys
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.EXPAND_CHANGE,
+      {
+        key: entry.key,
+        expanded: expandedKeys.includes(entry.key),
+      }
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     activeKeyRef: import('vue').Ref<string | null>
+ *     expandedKeysRef: import('vue').Ref<Array<string>>
+ *   }
+ * }} FuroSidebarContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroSidebarContextParams, 'refHash'> & {
+ *   refHash?: FuroSidebarContextParams['refHash']
+ * }} FuroSidebarContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroSidebarContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroSidebarParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroSidebar>`.
+ * JSON-serializable only.
+ *
+ * @typedef {{
+ *   groups?: Array<FuroSidebarGroup>
+ *   activeKey?: string | null
+ *   expandedKeys?: Array<string> | null
+ *   collapsed?: boolean
+ *   searchable?: boolean
+ *   searchValue?: string | null
+ *   searchPlaceholder?: string | null
+ *   searchLabel?: string
+ *   label?: string
+ * }} FuroSidebarParcel
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   label?: string | null
+ *   items?: Array<FuroSidebarItem>
+ * }} FuroSidebarGroup
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   label: string
+ *   icon?: string | null
+ *   disabled?: boolean
+ *   items?: Array<FuroSidebarSubItem>
+ * }} FuroSidebarItem
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   label: string
+ *   disabled?: boolean
+ * }} FuroSidebarSubItem
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   label: string | null
+ *   items: Array<ItemEntry>
+ * }} GroupEntry
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   label: string
+ *   icon: string | null
+ *   hasIcon: boolean
+ *   disabled: boolean
+ *   subItems: Array<SubItemEntry>
+ *   hasSubItems: boolean
+ * }} ItemEntry
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   label: string
+ *   disabled: boolean
+ * }} SubItemEntry
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   parentKey: string | null
+ * }} NavigatePayload
+ */
+
+/**
+ * @typedef {{
+ *   key: string
+ *   expanded: boolean
+ * }} ExpandChangePayload
+ */
+
+/**
+ * @typedef {import('../../atoms/FuroTextField/TextFieldEmitPayload.js').default} SidebarSearchPayload
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<typeof FuroSidebarContext.EMIT_EVENT_HASH, FuroSidebarSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   header: {}
+ *   footer: {}
+ *   search: {}
+ *   item: {
+ *     entry: ItemEntry
+ *     active: boolean
+ *     expanded: boolean
+ *     collapsed: boolean
+ *   }
+ *   'sub-item': {
+ *     entry: SubItemEntry
+ *     parent: ItemEntry
+ *     active: boolean
+ *   }
+ * }>} FuroSidebarSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroSidebarContext
+ * }} FuroSidebarSetup
+ */