@fiscozen/navbar 0.1.11 → 0.2.1

package/dist/src/FzNavbar.vue.d.ts

@@ -1,11 +1,8 @@
 import { FzNavbarProps } from './types';
+declare function handleMenuButtonClick(): void;
 declare function __VLS_template(): {
     attrs: Partial<{}>;
-    slots: Partial<Record<NonNullable<"notifications" | "user-menu">, (_: {
-        isHorizontal: boolean;
-        isVertical: boolean;
-        isMobile: true;
-    }) => any>> & {
+    slots: {
         'brand-logo'?(_: {
             isMobile: false;
             isHorizontal: boolean;
@@ -26,11 +23,25 @@ declare function __VLS_template(): {
             isVertical: boolean;
             isMobile: false;
         }): any;
+        notifications?(_: {
+            isHorizontal: boolean;
+            isVertical: boolean;
+            isMobile: true;
+        }): any;
         'user-menu'?(_: {
             isHorizontal: boolean;
             isMobile: false;
             isVertical: boolean;
         }): any;
+        'user-menu'?(_: {
+            isHorizontal: boolean;
+            isMobile: true;
+            isVertical: boolean;
+        }): any;
+        'menu-button'?(_: {
+            isOpen: boolean;
+            toggle: typeof handleMenuButtonClick;
+        }): any;
     };
     refs: {};
     rootEl: HTMLElement;
@@ -38,11 +49,16 @@ declare function __VLS_template(): {
 type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
 declare const __VLS_component: import('vue').DefineComponent<FzNavbarProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     "fznavbar:menuButtonClick": () => any;
+    "update:isMenuOpen": (value: boolean) => any;
 }, string, import('vue').PublicProps, Readonly<FzNavbarProps> & Readonly<{
     "onFznavbar:menuButtonClick"?: (() => any) | undefined;
+    "onUpdate:isMenuOpen"?: ((value: boolean) => any) | undefined;
 }>, {
     variant: import('./types').FzNavbarVariant;
+    position: import('./types').FzNavbarPosition;
     breakpoints: Partial<Record<import('@fiscozen/style').Breakpoint, `${number}px`>>;
+    mobileBreakpoint: number | `${number}px`;
+    respectSafeArea: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLElement>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;

package/dist/src/types.d.ts

@@ -1,20 +1,44 @@
 import { Breakpoint } from '@fiscozen/style';
 export type FzNavbarVariant = 'horizontal' | 'vertical';
+export type FzNavbarPosition = 'static' | 'fixed' | 'sticky';
 interface FzNavbarProps {
     /**
      * The main direction of the navbar
      */
-    variant: FzNavbarVariant;
+    variant?: FzNavbarVariant;
     /**
-     * Whether the main navigation menu is open (mobile)
+     * Whether the main navigation menu is open (mobile). Supports v-model.
      */
     isMenuOpen?: boolean;
     /**
-     * Override breakpoint for manage custom size inside navbar
+     * @deprecated Use `mobileBreakpoint` instead. When both are passed, `mobileBreakpoint` takes precedence.
+     *
+     * Override breakpoints for managing custom size inside the navbar.
      */
     breakpoints?: Partial<Record<Breakpoint, `${number}px`>>;
+    /**
+     * Width (in pixels) at and above which the navbar renders its desktop layout.
+     * Below this value the compact mobile layout is used.
+     *
+     * Replaces the global mutation of `@fiscozen/style` breakpoints that consumers
+     * used to perform to align with their own desktop threshold.
+     */
+    mobileBreakpoint?: number | `${number}px`;
+    /**
+     * CSS positioning strategy applied to the root `<header>`. Replaces the need
+     * for consumers to add `class="fixed top-0 left-0"` (or similar) on the call site.
+     */
+    position?: FzNavbarPosition;
+    /**
+     * When `true`, the navbar adds `env(safe-area-inset-*)` to its top, left and right padding
+     * so it renders correctly on devices with a notch / dynamic island.
+     *
+     * Defaults to `false` to preserve current visual behavior for existing consumers.
+     */
+    respectSafeArea?: boolean;
 }
 type FzNavbarEmits = {
     'fznavbar:menuButtonClick': [];
+    'update:isMenuOpen': [value: boolean];
 };
 export type { FzNavbarProps, FzNavbarEmits };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiscozen/navbar",
-  "version": "0.1.11",
+  "version": "0.2.1",
   "description": "Design System Navbar Component",
   "main": "src/index.ts",
   "type": "module",
@@ -32,8 +32,8 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@fiscozen/composables": "1.0.3",
     "@fiscozen/button": "3.0.1",
+    "@fiscozen/composables": "1.0.3",
     "@fiscozen/style": "0.3.0"
   },
   "scripts": {

package/src/FzNavbar.vue

@@ -7,29 +7,59 @@ import { useBreakpoints } from '@fiscozen/composables'
 
 const props = withDefaults(defineProps<FzNavbarProps>(), {
   variant: 'horizontal',
-  breakpoints: undefined
+  breakpoints: undefined,
+  mobileBreakpoint: undefined,
+  position: 'static',
+  respectSafeArea: false
 })
 
+const emit = defineEmits<FzNavbarEmits>()
+
+if (props.breakpoints !== undefined) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[FzNavbar] The `breakpoints` prop is deprecated and will be removed in a future major. Use `mobileBreakpoint` instead.'
+  )
+}
+
 const computedBreakpoints = computed(() => {
+  if (props.mobileBreakpoint !== undefined) {
+    const value =
+      typeof props.mobileBreakpoint === 'number'
+        ? (`${props.mobileBreakpoint}px` as `${number}px`)
+        : props.mobileBreakpoint
+    return { ...breakpoints, lg: value }
+  }
   return {
     ...breakpoints,
     ...(props.breakpoints ?? {})
   }
 })
 
-const emit = defineEmits<FzNavbarEmits>()
-
 const { isGreater } = useBreakpoints(computedBreakpoints.value)
 const isGreaterThanLg = isGreater('lg')
 const isMobile = computed(() => !isGreaterThanLg.value)
-const isVertical = computed(() => Boolean(props.variant === 'vertical'))
-const isHorizontal = computed(() => Boolean(props.variant === 'horizontal'))
+const isVertical = computed(() => props.variant === 'vertical')
+const isHorizontal = computed(() => props.variant === 'horizontal')
+
+const localMenuOpen = computed<boolean | undefined>({
+  get: () => props.isMenuOpen,
+  set: (value) => emit('update:isMenuOpen', Boolean(value))
+})
+
+function handleMenuButtonClick() {
+  localMenuOpen.value = !localMenuOpen.value
+  emit('fznavbar:menuButtonClick')
+}
 </script>
 
 <template>
   <header
-    class="z-10 flex p-12 shadow"
+    class="fz-navbar z-10 m-0 box-border flex items-center border-0 p-12 shadow"
     :class="{
+      'fz-navbar--fixed': position === 'fixed',
+      'fz-navbar--sticky': position === 'sticky',
+      'fz-navbar--safe-area': respectSafeArea,
       'justify-between': isMobile,
       'h-full w-56 flex-col': isVertical && !isMobile,
       'h-56 w-full': isHorizontal || isMobile
@@ -39,11 +69,14 @@ const isHorizontal = computed(() => Boolean(props.variant === 'horizontal'))
       <div :class="{ 'mr-32': isHorizontal, 'mb-32': isVertical }">
         <slot name="brand-logo" :isMobile :isHorizontal :isVertical></slot>
       </div>
-      <div class="flex gap-4" :class="{ 'flex-row': isHorizontal, 'flex-col': isVertical }">
+      <div
+        class="flex items-center gap-4"
+        :class="{ 'flex-row': isHorizontal, 'flex-col': isVertical }"
+      >
         <slot name="navigation" :isVertical :isHorizontal :isMobile></slot>
       </div>
       <div
-        class="flex gap-16"
+        class="flex items-center gap-16"
         :class="{ 'ml-auto flex-row': isHorizontal, 'mt-auto flex-col': isVertical }"
       >
         <slot name="notifications" :isHorizontal :isVertical :isMobile></slot>
@@ -51,25 +84,93 @@ const isHorizontal = computed(() => Boolean(props.variant === 'horizontal'))
       </div>
     </template>
     <template v-else>
-      <FzIconButton
-        :iconName="isMenuOpen ? 'xmark' : 'bars'"
-        variant="secondary"
-        tooltip="menu"
-        @click="emit('fznavbar:menuButtonClick')"
-      />
+      <slot name="menu-button" :isOpen="Boolean(localMenuOpen)" :toggle="handleMenuButtonClick">
+        <FzIconButton
+          :iconName="localMenuOpen ? 'xmark' : 'bars'"
+          variant="secondary"
+          tooltip="menu"
+          @click="handleMenuButtonClick"
+        />
+      </slot>
       <div>
         <slot name="brand-logo" :isMobile :isHorizontal :isVertical></slot>
       </div>
-      <div>
-        <slot
-          :name="isHorizontal ? 'notifications' : 'user-menu'"
-          :isHorizontal
-          :isVertical
-          :isMobile
-        ></slot>
+      <div class="flex items-center gap-16">
+        <slot name="notifications" :isHorizontal :isVertical :isMobile></slot>
+        <slot name="user-menu" :isHorizontal :isMobile :isVertical></slot>
       </div>
     </template>
   </header>
 </template>
 
-<style></style>
+<style>
+/*
+ * CSS custom properties — defaults are pinned to the `@fiscozen/style` pixel
+ * spacing tokens that match the Tailwind utility classes used in the template
+ * (p-12 = 12px, h-56/w-56 = 56px, mr-32/mb-32 = 32px, gap-16 = 16px). The
+ * package's CSS rule `.fz-navbar.{w-56,h-56,...}` has higher specificity than
+ * the consumer's generated Tailwind class on its own, so the fallback values
+ * must match the design-system pixel scale — otherwise stock-Tailwind rem
+ * defaults (14rem/3rem/8rem/4rem) leak through and the navbar renders ~4×
+ * larger than intended.
+ *
+ * Consumers can still override per-instance via inline style or scoped CSS.
+ */
+
+.fz-navbar {
+  z-index: var(--fz-navbar-z-index, 10);
+  padding: var(--fz-navbar-padding, 12px);
+  box-shadow: var(
+    --fz-navbar-shadow,
+    0 1px 3px 0 rgb(0 0 0 / 0.1),
+    0 1px 2px -1px rgb(0 0 0 / 0.1)
+  );
+  background: var(--fz-navbar-bg, transparent);
+}
+
+.fz-navbar.h-56 {
+  height: var(--fz-navbar-height, 56px);
+}
+
+.fz-navbar.w-56 {
+  width: var(--fz-navbar-width, 56px);
+}
+
+.fz-navbar > .mr-32 {
+  margin-right: var(--fz-navbar-brand-gap, 32px);
+}
+
+.fz-navbar > .mb-32 {
+  margin-bottom: var(--fz-navbar-brand-gap, 32px);
+}
+
+.fz-navbar > .gap-16 {
+  gap: var(--fz-navbar-actions-gap, 16px);
+}
+
+.fz-navbar--fixed {
+  position: fixed;
+  top: 0;
+  left: 0;
+}
+
+.fz-navbar--sticky {
+  position: sticky;
+  top: 0;
+}
+
+.fz-navbar--safe-area {
+  padding-top: calc(
+    var(--fz-navbar-padding, 12px) +
+      max(env(safe-area-inset-top, 0px), var(--safe-area-inset-top, 0px))
+  );
+  padding-left: calc(
+    var(--fz-navbar-padding, 12px) +
+      max(env(safe-area-inset-left, 0px), var(--safe-area-inset-left, 0px))
+  );
+  padding-right: calc(
+    var(--fz-navbar-padding, 12px) +
+      max(env(safe-area-inset-right, 0px), var(--safe-area-inset-right, 0px))
+  );
+}
+</style>

package/src/__tests__/FzNavbar.spec.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import { mount, VueWrapper } from '@vue/test-utils'
 import FzNavbar from '../FzNavbar.vue'
 import { FzIconButton } from '@fiscozen/button'
+import { breakpoints } from '@fiscozen/style'
 
 const navigation = `
   <div class="link">one</div>
@@ -847,4 +848,277 @@ describe('FzNavbar', () => {
       expect(wrapper.html()).toMatchSnapshot()
     })
   })
+
+  // ============================================
+  // v0.2.0 — ADDITIVE API
+  // ============================================
+  describe('mobileBreakpoint prop', () => {
+    it('should accept a numeric value', () => {
+      wrapper = mount(FzNavbar, {
+        props: {
+          variant: 'horizontal',
+          mobileBreakpoint: 1200
+        }
+      })
+      expect(wrapper.exists()).toBe(true)
+    })
+
+    it('should accept a pixel-string value', () => {
+      wrapper = mount(FzNavbar, {
+        props: {
+          variant: 'horizontal',
+          mobileBreakpoint: '1200px'
+        }
+      })
+      expect(wrapper.exists()).toBe(true)
+    })
+
+    it('should not mutate the imported @fiscozen/style breakpoints object', () => {
+      const before = { ...breakpoints }
+      mount(FzNavbar, {
+        props: {
+          variant: 'horizontal',
+          mobileBreakpoint: 1400
+        }
+      })
+      expect(breakpoints).toEqual(before)
+    })
+
+    it('should take precedence over the legacy `breakpoints` prop when both are provided', () => {
+      wrapper = mount(FzNavbar, {
+        props: {
+          variant: 'horizontal',
+          breakpoints: { lg: '900px' },
+          mobileBreakpoint: 1500
+        }
+      })
+      expect(wrapper.exists()).toBe(true)
+    })
+  })
+
+  describe('position prop', () => {
+    it('should not add positioning classes by default', () => {
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal' }
+      })
+      const header = wrapper.find('header')
+      expect(header.classes()).not.toContain('fz-navbar--fixed')
+      expect(header.classes()).not.toContain('fz-navbar--sticky')
+    })
+
+    it('should add the fixed-position class when position="fixed"', () => {
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', position: 'fixed' }
+      })
+      expect(wrapper.find('header').classes()).toContain('fz-navbar--fixed')
+    })
+
+    it('should add the sticky-position class when position="sticky"', () => {
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', position: 'sticky' }
+      })
+      expect(wrapper.find('header').classes()).toContain('fz-navbar--sticky')
+    })
+  })
+
+  describe('respectSafeArea prop', () => {
+    it('should not add the safe-area class by default', () => {
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal' }
+      })
+      expect(wrapper.find('header').classes()).not.toContain('fz-navbar--safe-area')
+    })
+
+    it('should add the safe-area class when respectSafeArea is true', () => {
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', respectSafeArea: true }
+      })
+      expect(wrapper.find('header').classes()).toContain('fz-navbar--safe-area')
+    })
+  })
+
+  describe('v-model:isMenuOpen', () => {
+    it('should emit update:isMenuOpen when the default menu button is clicked', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', isMenuOpen: false }
+      })
+      await wrapper.vm.$nextTick()
+      const menuButton = wrapper.findComponent(FzIconButton)
+      const buttonElement = menuButton.find('button')
+      await (buttonElement.exists() ? buttonElement : menuButton).trigger('click')
+
+      const updates = wrapper.emitted('update:isMenuOpen')
+      expect(updates).toBeTruthy()
+      expect(updates![0]).toEqual([true])
+    })
+
+    it('should emit `false` when toggling from an open state', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', isMenuOpen: true }
+      })
+      await wrapper.vm.$nextTick()
+      const menuButton = wrapper.findComponent(FzIconButton)
+      const buttonElement = menuButton.find('button')
+      await (buttonElement.exists() ? buttonElement : menuButton).trigger('click')
+
+      const updates = wrapper.emitted('update:isMenuOpen')
+      expect(updates).toBeTruthy()
+      expect(updates![0]).toEqual([false])
+    })
+
+    it('should still emit fznavbar:menuButtonClick alongside update:isMenuOpen', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', isMenuOpen: false }
+      })
+      await wrapper.vm.$nextTick()
+      const menuButton = wrapper.findComponent(FzIconButton)
+      const buttonElement = menuButton.find('button')
+      await (buttonElement.exists() ? buttonElement : menuButton).trigger('click')
+
+      expect(wrapper.emitted('fznavbar:menuButtonClick')).toHaveLength(1)
+      expect(wrapper.emitted('update:isMenuOpen')).toHaveLength(1)
+    })
+  })
+
+  describe('menu-button slot', () => {
+    it('should render the default FzIconButton when the slot is not provided', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal' }
+      })
+      await wrapper.vm.$nextTick()
+      expect(wrapper.findComponent(FzIconButton).exists()).toBe(true)
+    })
+
+    it('should replace the default button when the menu-button slot is provided', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', isMenuOpen: false },
+        slots: {
+          'menu-button': `
+            <template #menu-button="{ isOpen, toggle }">
+              <button id="custom-menu" :data-is-open="isOpen" @click="toggle">menu</button>
+            </template>
+          `
+        }
+      })
+      await wrapper.vm.$nextTick()
+      expect(wrapper.find('#custom-menu').exists()).toBe(true)
+      expect(wrapper.findComponent(FzIconButton).exists()).toBe(false)
+    })
+
+    it('should expose isOpen and toggle in the slot scope', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal', isMenuOpen: true },
+        slots: {
+          'menu-button': `
+            <template #menu-button="{ isOpen, toggle }">
+              <button id="custom-menu" :data-is-open="isOpen" @click="toggle">menu</button>
+            </template>
+          `
+        }
+      })
+      await wrapper.vm.$nextTick()
+      const customButton = wrapper.find('#custom-menu')
+      expect(customButton.attributes('data-is-open')).toBe('true')
+
+      await customButton.trigger('click')
+      const updates = wrapper.emitted('update:isMenuOpen')
+      expect(updates).toBeTruthy()
+      expect(updates![0]).toEqual([false])
+    })
+  })
+
+  describe('mobile slot rendering (no XOR)', () => {
+    it('should render both notifications and user-menu slots on mobile when both are filled', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal' },
+        slots: {
+          notifications: '<div id="notification"></div>',
+          'user-menu': '<div id="avatar"></div>'
+        }
+      })
+      await wrapper.vm.$nextTick()
+      expect(wrapper.find('#notification').exists()).toBe(true)
+      expect(wrapper.find('#avatar').exists()).toBe(true)
+    })
+
+    it('should render only notifications on mobile when user-menu is empty', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'horizontal' },
+        slots: {
+          notifications: '<div id="notification"></div>'
+        }
+      })
+      await wrapper.vm.$nextTick()
+      expect(wrapper.find('#notification').exists()).toBe(true)
+      expect(wrapper.find('#avatar').exists()).toBe(false)
+    })
+
+    it('should render only user-menu on mobile when notifications is empty', async () => {
+      window.innerWidth = 1023
+      vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1023)
+
+      wrapper = mount(FzNavbar, {
+        props: { variant: 'vertical' },
+        slots: {
+          'user-menu': '<div id="avatar"></div>'
+        }
+      })
+      await wrapper.vm.$nextTick()
+      expect(wrapper.find('#avatar').exists()).toBe(true)
+      expect(wrapper.find('#notification').exists()).toBe(false)
+    })
+  })
+
+  describe('breakpoints prop deprecation warning', () => {
+    it('should emit a console.warn in dev when the deprecated `breakpoints` prop is used', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      mount(FzNavbar, {
+        props: {
+          variant: 'horizontal',
+          breakpoints: { lg: '1200px' }
+        }
+      })
+
+      expect(warnSpy).toHaveBeenCalled()
+      expect(warnSpy.mock.calls[0][0]).toMatch(/breakpoints.*deprecated/i)
+
+      warnSpy.mockRestore()
+    })
+
+    it('should not warn when the deprecated prop is not used', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      mount(FzNavbar, {
+        props: { variant: 'horizontal' }
+      })
+
+      expect(warnSpy).not.toHaveBeenCalled()
+      warnSpy.mockRestore()
+    })
+  })
 })