@livestorm/ui-vue 1.1.2 → 2.0.0

package/src/components/UiTimeline/UiTimelineItem.vue

@@ -0,0 +1,141 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+interface Props {
+  /** Visual variant of the timeline item */
+  variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger'
+  /** Whether to show the connecting line */
+  showConnector?: boolean
+  /** Size of the indicator dot */
+  indicatorSize?: 'sm' | 'md' | 'lg'
+  /** Custom icon class for the indicator (optional) */
+  indicatorIcon?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  variant: 'default',
+  showConnector: true,
+  indicatorSize: 'md',
+  indicatorIcon: undefined,
+})
+
+const indicatorClasses = computed(() => {
+  const baseClasses = [
+    'ui-timeline-item__indicator',
+    'flex',
+    'items-center',
+    'justify-center',
+    'rounded-full',
+    'shrink-0',
+  ]
+
+  // Size classes
+  const sizeClasses = {
+    sm: props.indicatorIcon ? ['w-5', 'h-5'] : ['w-2', 'h-2'],
+    md: props.indicatorIcon ? ['w-6', 'h-6'] : ['w-3', 'h-3'],
+    lg: props.indicatorIcon ? ['w-8', 'h-8'] : ['w-4', 'h-4'],
+  }
+
+  // Variant classes
+  const variantClasses = {
+    default: props.indicatorIcon
+      ? ['bg-surface-neutral-alpha-200', 'text-text-neutral-base']
+      : ['bg-surface-neutral-alpha-300'],
+    primary: props.indicatorIcon
+      ? ['bg-surface-primary-alpha-200', 'text-text-primary-base']
+      : ['bg-surface-primary-bg-alpha'],
+    success: props.indicatorIcon
+      ? ['bg-surface-success-alpha-200', 'text-text-success-base']
+      : ['bg-surface-success-bg-alpha'],
+    warning: props.indicatorIcon
+      ? ['bg-surface-warning-alpha-200', 'text-text-warning-base']
+      : ['bg-surface-warning-bg-alpha'],
+    danger: props.indicatorIcon
+      ? ['bg-surface-danger-bg-alpha', 'text-text-neutral-invert-base']
+      : ['bg-surface-danger-bg-alpha'],
+  }
+
+  return [
+    ...baseClasses,
+    ...sizeClasses[props.indicatorSize],
+    ...variantClasses[props.variant],
+  ]
+})
+
+const connectorClasses = computed(() => {
+  const variantClasses = {
+    default: 'bg-surface-neutral-alpha-400',
+    primary: 'bg-surface-primary-alpha-300',
+    success: 'bg-surface-success-alpha-300',
+    warning: 'bg-surface-warning-alpha-300',
+    danger: 'bg-surface-danger-alpha-400',
+  }
+
+  return ['ui-timeline-item__connector', variantClasses[props.variant]]
+})
+
+const iconSize = computed(() => {
+  const sizes = {
+    sm: 'w-1 h-1',
+    md: 'w-2 h-2',
+    lg: 'w-3 h-3',
+  }
+  return sizes[props.indicatorSize]
+})
+</script>
+
+<template>
+  <div class="ui-timeline-item">
+    <!-- Left side: Indicator and connector -->
+    <div class="ui-timeline-item__indicator-wrapper">
+      <!-- Indicator -->
+      <div :class="indicatorClasses">
+        <span
+          v-if="indicatorIcon"
+          :class="[indicatorIcon, iconSize]"
+        />
+      </div>
+
+      <!-- Connector line -->
+      <div
+        v-if="showConnector"
+        :class="connectorClasses"
+      />
+    </div>
+
+    <!-- Right side: Content -->
+    <div class="ui-timeline-item__content">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<style>
+@reference '@livestorm/ui-tokens/output/supernova/index.css';
+.ui-timeline-item {
+  @apply flex gap-4 relative;
+}
+
+.ui-timeline-item__indicator-wrapper {
+  @apply flex flex-col items-center shrink-0 self-stretch;
+}
+
+.ui-timeline-item__connector {
+  @apply w-px flex-1 mt-2 mb-2;
+  min-height: 2rem;
+}
+
+.ui-timeline-item__content {
+  @apply flex-1 pb-4;
+}
+
+/* Remove bottom padding from last item */
+.ui-timeline-item:last-child .ui-timeline-item__content {
+  @apply pb-0;
+}
+
+/* Hide connector for last item */
+.ui-timeline-item:last-child .ui-timeline-item__connector {
+  @apply hidden;
+}
+</style>

package/src/components/UiTimeline/index.ts

@@ -0,0 +1,2 @@
+export { default as UiTimeline } from './UiTimeline.vue'
+export { default as UiTimelineItem } from './UiTimelineItem.vue'

package/src/components/UiTooltip/UiTooltip.vue

@@ -0,0 +1,16 @@
+<!-- UiTooltip.vue -->
+<script setup lang="ts">
+import type { TooltipRootEmits, TooltipRootProps } from 'reka-ui'
+import { TooltipRoot, useForwardPropsEmits } from 'reka-ui'
+
+const props = defineProps<TooltipRootProps>()
+const emits = defineEmits<TooltipRootEmits>()
+
+const forwarded = useForwardPropsEmits(props, emits)
+</script>
+
+<template>
+  <TooltipRoot v-bind="{ ...forwarded, ...$attrs }">
+    <slot />
+  </TooltipRoot>
+</template>

package/src/components/UiTooltip/UiTooltipContent.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { TooltipContentEmits, TooltipContentProps } from 'reka-ui'
+import { TooltipContent, TooltipPortal, TooltipArrow, useForwardPropsEmits } from 'reka-ui'
+
+interface Props extends TooltipContentProps {
+  /**
+   * The color semantic mode for the tooltip
+   * @default 'light'
+   */
+  colorsSemantic?: 'light' | 'dark'
+  /**
+   * The maximum width of the tooltip
+   * @default 'base'
+   */
+  maxWidth?: 'xs' | 'sm' | 'md' | 'base' | 'lg' | 'xl'
+  /**
+   * Whether to show the arrow pointing to the trigger
+   * @default true
+   */
+  showArrow?: boolean
+  /**
+   * Width of the arrow in pixels
+   * @default 10
+   */
+  arrowWidth?: number
+  /**
+   * Height of the arrow in pixels
+   * @default 5
+   */
+  arrowHeight?: number
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  sideOffset: 12,
+  colorsSemantic: 'light',
+  maxWidth: 'base',
+  showArrow: true,
+  arrowWidth: 10,
+  arrowHeight: 5,
+})
+
+const emits = defineEmits<TooltipContentEmits>()
+
+const forwarded = useForwardPropsEmits(props, emits)
+
+const maxWidthClass = computed(() => {
+  const widthMap = {
+    xs: 'max-w-[150px]',
+    sm: 'max-w-[240px]',
+    md: 'max-w-md',
+    base: 'max-w-xs',
+    lg: 'max-w-lg',
+    xl: 'max-w-xl',
+  }
+  return widthMap[props.maxWidth]
+})
+</script>
+
+<template>
+  <TooltipPortal>
+    <TooltipContent
+      v-bind="{ ...forwarded, ...$attrs }"
+      :data-colors-semantic="props.colorsSemantic"
+      :class="[
+        'ui-tooltip-content py-1.5 px-3 bg-surface-neutral-invert-bg-alpha text-text-neutral-invert-base text-content-text-md-regular rounded-md text-center z-50 shadow-shadows-drop-shadow-lg',
+        'data-[state=delayed-open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=delayed-open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=delayed-open]:zoom-in-95',
+        maxWidthClass
+      ]"
+    >
+      <slot />
+      <TooltipArrow
+        v-if="props.showArrow"
+        :width="props.arrowWidth"
+        :height="props.arrowHeight"
+        class="fill-surface-neutral-invert-bg-alpha"
+      />
+    </TooltipContent>
+  </TooltipPortal>
+</template>
+
+<style>
+.ui-tooltip-content {
+  transform-origin: var(--reka-tooltip-content-transform-origin, center);
+}
+</style>

package/src/components/UiTooltip/UiTooltipProvider.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { TooltipProviderProps } from 'reka-ui'
+import { TooltipProvider } from 'reka-ui'
+
+withDefaults(defineProps<TooltipProviderProps>(), {
+  delayDuration: 700,
+  skipDelayDuration: 300,
+})
+</script>
+
+<template>
+  <TooltipProvider v-bind="$props">
+    <slot />
+  </TooltipProvider>
+</template>

package/src/components/UiTooltip/UiTooltipTrigger.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import type { TooltipTriggerProps } from 'reka-ui'
+import { TooltipTrigger, useForwardProps } from 'reka-ui'
+
+const props = defineProps<TooltipTriggerProps>()
+
+// Forward declared props (e.g. `asChild`) to reka — otherwise they'd be
+// consumed here and never reach TooltipTrigger, so `as-child` would be ignored
+// and reka would wrap the slot in its own <button>.
+const forwarded = useForwardProps(props)
+</script>
+
+<template>
+  <TooltipTrigger
+    v-bind="{ ...forwarded, ...$attrs }"
+  >
+    <slot />
+  </TooltipTrigger>
+</template>

package/src/components/UiTooltip/index.js

@@ -0,0 +1,4 @@
+export { default as UiTooltip } from './UiTooltip.vue'
+export { default as UiTooltipTrigger } from './UiTooltipTrigger.vue'
+export { default as UiTooltipContent } from './UiTooltipContent.vue'
+export { default as UiTooltipProvider } from './UiTooltipProvider.vue'

package/src/composables/useButtonStyles.ts

@@ -0,0 +1,242 @@
+import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+
+// Single source of truth for the action-button visual language (background,
+// text, border, hover/active overlays) keyed by `variant` × `color`. Both
+// `UiButton` and `UiDropdownTrigger` consume this so a trigger styled as a
+// tertiary button stays pixel-identical to a real `UiButton` without copying
+// token names around.
+//
+// NOTE: every class here must be a complete literal string — Tailwind's static
+// extractor can't see interpolated class names (`bg-${token}`), so the overlay
+// maps are split per pseudo-prefix (`group-hover:` for the layered button,
+// `before:` for the single-element trigger) rather than built at runtime.
+
+export const BUTTON_VARIANTS = ['cta', 'cta-alpha', 'secondary', 'tertiary'] as const
+export type ButtonVariant = typeof BUTTON_VARIANTS[number]
+
+export const BUTTON_COLORS = ['primary', 'neutral', 'success', 'warning', 'error', 'neutral-invert'] as const
+export type ButtonColor = typeof BUTTON_COLORS[number]
+
+// Resting background — only the filled variants paint one. `tertiary` is
+// transparent at rest (just text + hover overlay).
+const BG_MAP: Partial<Record<ButtonVariant, Record<ButtonColor, string>>> = {
+  'cta': {
+    'primary': 'bg-actions-primary-idle',
+    'neutral': 'bg-actions-neutral-idle',
+    'neutral-invert': 'bg-actions-neutral-invert-idle',
+    'success': 'bg-actions-success-idle',
+    'warning': 'bg-actions-warning-idle',
+    'error': 'bg-actions-danger-idle',
+  },
+  'cta-alpha': {
+    'primary': 'bg-actions-primary-idle-alpha-strong',
+    'neutral': 'bg-actions-neutral-idle-alpha-strong',
+    'neutral-invert': 'bg-actions-neutral-invert-idle-alpha-strong',
+    'success': 'bg-actions-success-idle-alpha-strong',
+    'warning': 'bg-actions-warning-idle-alpha-strong',
+    'error': 'bg-actions-danger-idle-alpha-strong',
+  },
+  'secondary': {
+    'primary': 'bg-actions-primary-idle-alpha-light',
+    'neutral': 'bg-actions-neutral-idle-alpha-light',
+    'neutral-invert': 'bg-actions-neutral-invert-idle-alpha-light',
+    'success': 'bg-actions-success-idle-alpha-light',
+    'warning': 'bg-actions-warning-idle-alpha-light',
+    'error': 'bg-actions-danger-idle-alpha-light',
+  },
+}
+
+const TEXT_MAP: Record<ButtonVariant, Record<ButtonColor, string>> = {
+  'cta': {
+    'primary': 'text-actions-neutral-invert-idle',
+    'neutral': 'text-actions-neutral-invert-idle',
+    'neutral-invert': 'text-actions-neutral-idle',
+    'success': 'text-actions-neutral-invert-idle',
+    'warning': 'text-actions-neutral-invert-idle',
+    'error': 'text-actions-neutral-invert-idle',
+  },
+  'cta-alpha': {
+    'primary': 'text-actions-neutral-invert-idle',
+    'neutral': 'text-actions-neutral-invert-idle',
+    'neutral-invert': 'text-actions-neutral-idle',
+    'success': 'text-actions-neutral-invert-idle',
+    'warning': 'text-actions-neutral-invert-idle',
+    'error': 'text-actions-neutral-invert-idle',
+  },
+  'secondary': {
+    'primary': 'text-actions-primary-idle',
+    'neutral': 'text-actions-neutral-idle',
+    'neutral-invert': 'text-actions-neutral-invert-idle',
+    'success': 'text-actions-success-idle',
+    'warning': 'text-actions-warning-idle',
+    'error': 'text-actions-danger-idle',
+  },
+  'tertiary': {
+    'primary': 'text-actions-primary-idle',
+    'neutral': 'text-actions-neutral-idle',
+    'neutral-invert': 'text-actions-neutral-invert-idle',
+    'success': 'text-actions-success-idle',
+    'warning': 'text-actions-warning-idle',
+    'error': 'text-actions-danger-idle',
+  },
+}
+
+// Border — only `secondary` draws one.
+const BORDER_MAP: Record<ButtonColor, string[]> = {
+  'primary': ['border', 'border-borders-primary-strong'],
+  'neutral': ['border', 'border-borders-neutral-strong'],
+  'neutral-invert': ['border', 'border-borders-neutral-invert-strong'],
+  'success': ['border', 'border-borders-success-strong'],
+  'warning': ['border', 'border-borders-warning-strong'],
+  'error': ['border', 'border-borders-danger-strong'],
+}
+
+// Hover overlay tints keyed by `variant-color`, in both the `group-hover:`
+// flavor (layered button overlay element) and the `before:` flavor
+// (single-element trigger pseudo). Kept as literals for Tailwind extraction.
+const HOVER_OVERLAY_GROUP: Record<string, string> = {
+  'cta-primary': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-neutral': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-neutral-invert': 'group-hover:bg-actions-neutral-hover-overlay',
+  'cta-success': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-warning': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-error': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+
+  'cta-alpha-primary': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-neutral': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-neutral-invert': 'group-hover:bg-actions-neutral-hover-overlay',
+  'cta-alpha-success': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-warning': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-error': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+
+  'secondary-primary': 'group-hover:bg-actions-primary-hover-overlay',
+  'secondary-neutral': 'group-hover:bg-actions-neutral-hover-overlay',
+  'secondary-neutral-invert': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'secondary-success': 'group-hover:bg-actions-success-hover-overlay',
+  'secondary-warning': 'group-hover:bg-actions-warning-hover-overlay',
+  'secondary-error': 'group-hover:bg-actions-danger-hover-overlay',
+
+  'tertiary-primary': 'group-hover:bg-actions-primary-hover-overlay',
+  'tertiary-neutral': 'group-hover:bg-actions-neutral-hover-overlay',
+  'tertiary-neutral-invert': 'group-hover:bg-actions-neutral-invert-hover-overlay',
+  'tertiary-success': 'group-hover:bg-actions-success-hover-overlay',
+  'tertiary-warning': 'group-hover:bg-actions-warning-hover-overlay',
+  'tertiary-error': 'group-hover:bg-actions-danger-hover-overlay',
+}
+
+const ACTIVE_OVERLAY_GROUP: Record<string, string> = {
+  'cta-primary': 'group-active:bg-actions-primary-pressed-overlay',
+  'cta-neutral': 'group-active:bg-actions-neutral-invert-pressed-overlay',
+  'cta-neutral-invert': 'group-active:bg-actions-neutral-pressed-overlay',
+  'cta-success': 'group-active:bg-actions-success-pressed-overlay',
+  'cta-warning': 'group-active:bg-actions-warning-pressed-overlay',
+  'cta-error': 'group-active:bg-actions-danger-pressed-overlay',
+
+  'cta-alpha-primary': 'group-active:bg-actions-primary-pressed-overlay',
+  'cta-alpha-neutral': 'group-active:bg-actions-neutral-pressed-overlay',
+  'cta-alpha-neutral-invert': 'group-active:bg-actions-neutral-invert-pressed-overlay',
+  'cta-alpha-success': 'group-active:bg-actions-neutral-pressed-overlay',
+  'cta-alpha-warning': 'group-active:bg-actions-danger-pressed-overlay',
+  'cta-alpha-error': 'group-active:bg-actions-danger-pressed-overlay',
+
+  'secondary-primary': 'group-active:bg-actions-primary-pressed-overlay',
+  'secondary-neutral': 'group-active:bg-actions-neutral-idle-alpha-light',
+  'secondary-neutral-invert': 'group-active:bg-actions-neutral-invert-idle-alpha-light',
+  'secondary-success': 'group-active:bg-actions-success-pressed-overlay',
+  'secondary-warning': 'group-active:bg-actions-warning-pressed-overlay',
+  'secondary-error': 'group-active:bg-actions-danger-pressed-overlay',
+
+  'tertiary-primary': 'group-active:bg-actions-primary-pressed-overlay',
+  'tertiary-neutral': 'group-active:bg-actions-neutral-pressed-overlay',
+  'tertiary-neutral-invert': 'group-active:bg-actions-neutral-invert-pressed-overlay',
+  'tertiary-success': 'group-active:bg-actions-success-pressed-overlay',
+  'tertiary-warning': 'group-active:bg-actions-warning-pressed-overlay',
+  'tertiary-error': 'group-active:bg-actions-danger-pressed-overlay',
+}
+
+// `before:`-prefixed hover overlay, for the single-element trigger that paints
+// its overlay through a `::before` pseudo rather than a sibling div.
+const HOVER_OVERLAY_BEFORE: Record<string, string> = {
+  'cta-primary': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-neutral': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-neutral-invert': 'before:bg-actions-neutral-hover-overlay',
+  'cta-success': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-warning': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-error': 'before:bg-actions-neutral-invert-hover-overlay',
+
+  'cta-alpha-primary': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-neutral': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-neutral-invert': 'before:bg-actions-neutral-hover-overlay',
+  'cta-alpha-success': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-warning': 'before:bg-actions-neutral-invert-hover-overlay',
+  'cta-alpha-error': 'before:bg-actions-neutral-invert-hover-overlay',
+
+  'secondary-primary': 'before:bg-actions-primary-hover-overlay',
+  'secondary-neutral': 'before:bg-actions-neutral-hover-overlay',
+  'secondary-neutral-invert': 'before:bg-actions-neutral-invert-hover-overlay',
+  'secondary-success': 'before:bg-actions-success-hover-overlay',
+  'secondary-warning': 'before:bg-actions-warning-hover-overlay',
+  'secondary-error': 'before:bg-actions-danger-hover-overlay',
+
+  'tertiary-primary': 'before:bg-actions-primary-hover-overlay',
+  'tertiary-neutral': 'before:bg-actions-neutral-hover-overlay',
+  'tertiary-neutral-invert': 'before:bg-actions-neutral-invert-hover-overlay',
+  'tertiary-success': 'before:bg-actions-success-hover-overlay',
+  'tertiary-warning': 'before:bg-actions-warning-hover-overlay',
+  'tertiary-error': 'before:bg-actions-danger-hover-overlay',
+}
+
+export interface UseButtonStylesOptions {
+  variant: MaybeRefOrGetter<ButtonVariant>
+  color: MaybeRefOrGetter<ButtonColor>
+  /** When true, overlay classes resolve to empty (disabled/loading). */
+  disabled?: MaybeRefOrGetter<boolean>
+}
+
+export function useButtonStyles(options: UseButtonStylesOptions) {
+  const variant = computed(() => toValue(options.variant))
+  const color = computed(() => toValue(options.color))
+  const disabled = computed(() => toValue(options.disabled) ?? false)
+  const key = computed(() => `${variant.value}-${color.value}`)
+
+  /** Resting background class (filled variants only); `''` for tertiary. */
+  const bgClass = computed(() => BG_MAP[variant.value]?.[color.value] ?? '')
+
+  /** Text color class for the current variant × color. */
+  const textClass = computed(() => TEXT_MAP[variant.value][color.value])
+
+  /** Border classes — only `secondary` paints a border. */
+  const borderClasses = computed(() =>
+    variant.value === 'secondary' ? (BORDER_MAP[color.value] ?? []) : [],
+  )
+
+  /**
+   * Overlay classes for the layered-button pattern: a sibling overlay element
+   * tinted on `group-hover` / `group-active`. Empty when disabled.
+   */
+  const overlayClasses = computed(() => {
+    if (disabled.value) return []
+    return [
+      HOVER_OVERLAY_GROUP[key.value] ?? '',
+      ACTIVE_OVERLAY_GROUP[key.value] ?? '',
+    ]
+  })
+
+  /**
+   * Hover overlay class for the single-element pattern, applied through the
+   * element's own `::before` pseudo. Empty when disabled.
+   */
+  const beforeHoverOverlayClass = computed(() =>
+    disabled.value ? '' : (HOVER_OVERLAY_BEFORE[key.value] ?? ''),
+  )
+
+  return {
+    variant,
+    color,
+    bgClass,
+    textClass,
+    borderClasses,
+    overlayClasses,
+    beforeHoverOverlayClass,
+  }
+}

package/src/composables/useMobileMenu.ts

@@ -0,0 +1,57 @@
+// packages/ui-vue/src/composables/useMobileMenu.ts
+import { computed, ref } from 'vue'
+
+// Namespace for UI shell related state
+const UiShellState = {
+  isMobileMenuOpen: ref(false),
+  // Number of mounted components (e.g. UiPageHeader) that render their own
+  // open-menu trigger. UiShell uses this to decide whether it must provide a
+  // fallback hamburger, so a headerless page still has a way to open the menu.
+  triggerCount: ref(0),
+  // Label shown next to UiShell's fallback menu topbar. Pages set this (via
+  // setMenuLabel) to give the headerless mobile topbar a meaningful title
+  // (e.g. "Home"); null falls back to UiShell's openMenuLabel prop default.
+  menuLabel: ref<string | null>(null),
+}
+
+export function useMobileMenu () {
+  const toggle = () => {
+    UiShellState.isMobileMenuOpen.value = !UiShellState.isMobileMenuOpen.value
+  }
+
+  const open = () => {
+    UiShellState.isMobileMenuOpen.value = true
+  }
+
+  const close = () => {
+    UiShellState.isMobileMenuOpen.value = false
+  }
+
+  // Register/unregister an open-menu trigger. Call registerTrigger() on mount
+  // and unregisterTrigger() on unmount from any component that renders one.
+  const registerTrigger = () => {
+    UiShellState.triggerCount.value++
+  }
+
+  const unregisterTrigger = () => {
+    UiShellState.triggerCount.value = Math.max(0, UiShellState.triggerCount.value - 1)
+  }
+
+  // Set the fallback menu topbar label (e.g. from a page). Pass null to clear
+  // it — typically on unmount, so it doesn't leak to the next route.
+  const setMenuLabel = (label: string | null) => {
+    UiShellState.menuLabel.value = label
+  }
+
+  return {
+    isOpen: UiShellState.isMobileMenuOpen,
+    hasTrigger: computed(() => UiShellState.triggerCount.value > 0),
+    menuLabel: UiShellState.menuLabel,
+    toggle,
+    open,
+    close,
+    registerTrigger,
+    unregisterTrigger,
+    setMenuLabel,
+  }
+}