@mozaic-ds/vue 2.13.0 → 2.14.0

package/src/components/sidebar/MSidebar.spec.ts

@@ -0,0 +1,110 @@
+import { defineComponent, inject, ref } from 'vue';
+import { mount } from '@vue/test-utils';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import MSidebar from './MSidebar.vue';
+import { EXPANDED_SIDEBAR_KEY, TOGGLE_SIDEBAR_KEY } from './MSidebar.const';
+
+const isMobile = ref(false);
+
+vi.mock('../../utils/use-is-mobile.composable.ts', () => {
+  return {
+    useIsMobile: () => {
+      return {
+        isMobile: isMobile.value,
+      };
+    },
+  };
+});
+
+const MockedFooter = defineComponent({
+  name: 'MockedFooter',
+  setup() {
+    const expanded = inject(EXPANDED_SIDEBAR_KEY);
+    const toggle = inject(TOGGLE_SIDEBAR_KEY);
+    return { expanded, toggle };
+  },
+  template: `
+    <div>
+      <button data-test="toggle" @click="toggle">Toggle</button>
+    </div>
+  `,
+});
+
+describe('MSidebar', () => {
+  it('toggles expanded state and emits event when consumer calls toggle', async () => {
+    const wrapper = mount(MSidebar, {
+      global: { components: { MockedFooter } },
+      props: {
+        modelValue: true,
+      },
+      slots: {
+        header: '',
+        shortcuts: '',
+        nav: '',
+        footer: '<MockedFooter />',
+      },
+    });
+
+    const toggleBtn = wrapper.find('[data-test="toggle"]');
+    await toggleBtn.trigger('click');
+
+    const emitted = wrapper.emitted('update:modelValue') || [];
+    expect(emitted.length).toBe(1);
+    expect(emitted[0]).toEqual([false]);
+
+    await wrapper.setProps({ modelValue: emitted[0][0] as boolean });
+
+    const aside = wrapper.find('aside');
+    expect(aside.classes()).toContain('mc-sidebar--collapsed');
+  });
+
+  it('emits "close" when the close button is clicked', async () => {
+    const wrapper = mount(MSidebar, {
+      props: { modelValue: true },
+      global: {
+        stubs: ['MIconButton', 'Cross24'],
+      },
+    });
+
+    const btn = wrapper.find('.mc-sidebar__close-button');
+    await btn.trigger('click');
+
+    expect(wrapper.emitted()).toHaveProperty('close');
+    expect(wrapper.emitted('close')?.length).toBe(1);
+  });
+
+  describe('Resize handling', () => {
+    let addSpy: ReturnType<typeof vi.spyOn>;
+    let removeSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      vi.resetModules();
+      addSpy = vi.spyOn(window, 'addEventListener');
+      removeSpy = vi.spyOn(window, 'removeEventListener');
+    });
+
+    afterEach(() => {
+      addSpy.mockRestore();
+      removeSpy.mockRestore();
+      vi.clearAllMocks();
+    });
+
+    it('registers/unregisters resize listener and does not emit when isMobile is false', async () => {
+      isMobile.value = false;
+
+      const wrapper = mount(MSidebar, {
+        props: { modelValue: false },
+      });
+
+      expect(addSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+
+      window.dispatchEvent(new Event('resize'));
+
+      const emitted = wrapper.emitted('update:modelValue');
+      expect(emitted).toBeUndefined();
+
+      wrapper.unmount();
+      expect(removeSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+    });
+  });
+});

package/src/components/sidebar/MSidebar.stories.ts

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+
+import DefaultStory from './stories/DefaultCase.stories.vue';
+import WithExpandOnlyStory from './stories/WithExpandOnly.stories.vue';
+import WithProfileInfoOnlyStory from './stories/WithProfileInfoOnly.stories.vue';
+import WithSingleLevelStory from './stories/WithSingleLevel.stories.vue';
+import SourceCode from './stories/DefaultCase.stories.vue?raw';
+import MSidebar from './MSidebar.vue';
+import MSidebarHeader from '../sidebarheader/MSidebarHeader.vue';
+import MSidebarFooter from '../sidebarfooter/MSidebarFooter.vue';
+import MSidebarNavItem from '../sidebarnavitem/MSidebarNavItem.vue';
+import MSidebarShortcutItem from '../sidebarshortcutitem/MSidebarShortcutItem.vue';
+import MSidebarShortcuts from '../sidebarshortcuts/MSidebarShortcuts.vue';
+import MSidebarExpandableItem from '../sidebarexpandableitem/MSidebarExpandableItem.vue';
+import { action } from 'storybook/actions';
+
+const meta: Meta<typeof MSidebar> = {
+  title: 'Structure/Sidebar',
+  component: MSidebar,
+  subcomponents: {
+    MSidebarExpandableItem,
+    MSidebarHeader,
+    MSidebarFooter,
+    MSidebarNavItem,
+    MSidebarShortcuts,
+    MSidebarShortcutItem,
+  },
+  tags: ['v2'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      source: {
+        code: SourceCode,
+      },
+      description: {
+        component:
+          'A sidebar is a vertical navigation component that provides quick access to key sections and functionalities within an application or website. It contains expandable menus, and shortcuts, allowing users to navigate efficiently while keeping the main content area uncluttered. Sidebars can be collapsible or persistent, adapting to different screen sizes and user preferences. They are commonly used in dashboards, content management systems, and productivity tools.',
+      },
+    },
+  },
+  globals: {
+    backgrounds: { value: 'secondary' },
+  },
+  render: () => ({
+    setup() {
+      const handleClose = action('close');
+      const handleUpdateModelValue = action('update:modelValue');
+      const handleLogOut = action('log-out');
+
+      return {
+        handleClose,
+        handleUpdateModelValue,
+        handleLogOut,
+      };
+    },
+    components: { DefaultStory },
+    template: `
+      <DefaultStory
+        @close="handleClose"
+        @update:model-value="handleUpdateModelValue"
+        @log-out="handleLogOut"
+      />
+    `,
+  }),
+};
+export default meta;
+type Story = StoryObj<typeof MSidebar>;
+
+export const Default: Story = {};
+
+export const ExpandOnly: Story = {
+  render: () => ({
+    components: { WithExpandOnlyStory },
+    template: `
+      <WithExpandOnlyStory
+        @close="handleClose"
+        @update:model-value="handleUpdateModelValue"
+        @log-out="handleLogOut"
+      />
+    `,
+  }),
+};
+
+export const ProfileInfoOnly: Story = {
+  render: () => ({
+    components: { WithProfileInfoOnlyStory },
+    template: `
+      <WithProfileInfoOnlyStory
+        @close="handleClose"
+        @update:model-value="handleUpdateModelValue"
+        @log-out="handleLogOut"
+      />
+    `,
+  }),
+};
+
+export const SingleLevel: Story = {
+  render: () => ({
+    components: { WithSingleLevelStory },
+    template: `
+      <WithSingleLevelStory
+        @close="handleClose"
+        @update:model-value="handleUpdateModelValue"
+        @log-out="handleLogOut"
+      />
+    `,
+  }),
+};

package/src/components/sidebar/MSidebar.vue

@@ -0,0 +1,124 @@
+<template>
+  <aside
+    :class="[
+      'mc-sidebar',
+      `mc-sidebar--${expanded ? 'expanded' : 'collapsed'}`,
+    ]"
+  >
+    <div class="mc-sidebar__wrapper">
+      <slot name="header" />
+
+      <slot name="shortcuts" />
+
+      <section class="mc-sidebar__container">
+        <nav
+          class="mc-sidebar__menu"
+          role="navigation"
+          aria-label="navigation items"
+        >
+          <ul class="mc-sidebar__list">
+            <slot name="nav" />
+          </ul>
+        </nav>
+      </section>
+
+      <slot name="footer" />
+    </div>
+
+    <MIconButton
+      class="mc-sidebar__close-button"
+      ghost
+      aria-label="Sidebar close button"
+      @click="emit('close')"
+    >
+      <template #icon>
+        <Cross24 />
+      </template>
+    </MIconButton>
+  </aside>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, onUnmounted, provide, type VNode } from 'vue';
+import { EXPANDED_SIDEBAR_KEY, TOGGLE_SIDEBAR_KEY } from './MSidebar.const';
+import MIconButton from '../iconbutton/MIconButton.vue';
+import { Cross24 } from '@mozaic-ds/icons-vue';
+import { useIsMobile } from '@/utils/use-is-mobile.composable';
+
+/**
+ * A sidebar is a vertical navigation component that provides quick access to key sections and functionalities within an application or website. It contains expandable menus, and shortcuts, allowing users to navigate efficiently while keeping the main content area uncluttered. Sidebars can be collapsible or persistent, adapting to different screen sizes and user preferences. They are commonly used in dashboards, content management systems, and productivity tools.
+ */
+
+const props = defineProps<{
+  /**
+   * the state of the expanded sidebar, bound via v-model.
+   */
+  modelValue: boolean;
+}>();
+
+const emit = defineEmits<{
+  /**
+   * Emits when the sidebar state changes.
+   */
+  (on: 'update:modelValue', value: boolean): void; /**
+   * Emits when the sidebar close button is clicked (mobile only).
+   */
+  (on: 'close'): void;
+}>();
+
+defineSlots<{
+  /**
+   * Slot for the sidebar header. Should contain an `MSidebarHeader` component.
+   */
+  header: VNode[];
+  /**
+   * Slot for sidebar shortcuts. Should contain an `MSidebarShortcuts` component
+   * with one or more `MSidebarShortcutItem` components inside.
+   */
+  shortcuts: VNode[];
+  /**
+   * Slot for the main navigation items. Should contain one or more `MSidebarNavItem` components.
+   */
+  nav: VNode[];
+  /**
+   * Slot for the sidebar footer. Should contain an `MSidebarFooter` component.
+   */
+  footer: VNode[];
+}>();
+
+const expanded = computed({
+  get() {
+    return props.modelValue;
+  },
+  set(value) {
+    emit('update:modelValue', value);
+  },
+});
+
+function toggleSidebar() {
+  expanded.value = !expanded.value;
+}
+
+provide(EXPANDED_SIDEBAR_KEY, expanded);
+provide(TOGGLE_SIDEBAR_KEY, toggleSidebar);
+
+const { isMobile } = useIsMobile();
+
+function handleResize() {
+  if (isMobile.value) {
+    expanded.value = true;
+  }
+}
+
+onMounted(() => {
+  window.addEventListener('resize', handleResize);
+});
+
+onUnmounted(() => {
+  window.removeEventListener('resize', handleResize);
+});
+</script>
+
+<style lang="scss" scoped>
+@use '@mozaic-ds/styles/components/sidebar';
+</style>

package/src/components/sidebar/README.md

@@ -0,0 +1,59 @@
+# MSidebar
+
+A sidebar is a vertical navigation component that provides quick access to key sections and functionalities within an application or website. It contains expandable menus, and shortcuts, allowing users to navigate efficiently while keeping the main content area uncluttered. Sidebars can be collapsible or persistent, adapting to different screen sizes and user preferences. They are commonly used in dashboards, content management systems, and productivity tools.
+
+
+## Props
+
+| Name | Description | Type | Default |
+| --- | --- | --- | --- | 
+| `modelValue*` | the state of the expanded sidebar, bound via v-model. | `boolean` | - |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `header` | Slot for the sidebar header. Should contain an `MSidebarHeader` component. |
+| `shortcuts` | Slot for sidebar shortcuts. Should contain an `MSidebarShortcuts` component
+with one or more `MSidebarShortcutItem` components inside. |
+| `nav` | Slot for the main navigation items. Should contain one or more `MSidebarNavItem` components. |
+| `footer` | Slot for the sidebar footer. Should contain an `MSidebarFooter` component. |
+
+## Events
+
+| Name | Description | Type |
+| --- | --- | --- |
+| `update:modelValue` | Emits when the sidebar state changes. | [value: boolean] |
+| `close` | Emits when the sidebar close button is clicked (mobile only). | [] |
+
+## Dependencies
+
+### Depends on
+
+- [MIconButton](../iconbutton)
+
+### Graph
+
+```mermaid
+graph TD;
+  MSidebar --> MIconButton
+style MSidebar fill:#008240,stroke:#333,stroke-width:4px
+```
+
+### Used By
+
+- [DefaultCase.stories](stories)
+- [WithExpandOnly.stories](stories)
+- [WithProfileInfoOnly.stories](stories)
+- [WithSingleLevel.stories](stories)
+
+### Graph
+
+```mermaid
+graph TD;
+  DefaultCase.stories --> MSidebar
+  WithExpandOnly.stories --> MSidebar
+  WithProfileInfoOnly.stories --> MSidebar
+  WithSingleLevel.stories --> MSidebar
+style MSidebar fill:#008240,stroke:#333,stroke-width:4px
+```

package/src/components/sidebar/stories/DefaultCase.stories.vue

@@ -0,0 +1,120 @@
+<template>
+  <MSidebar
+    v-model="expanded"
+    @update:model-value="emit('update:modelValue')"
+    @close="emit('close')"
+  >
+    <template #header>
+      <MSidebarHeader title="Adeo Design System" logo="/logo.svg" />
+    </template>
+
+    <template #shortcuts>
+      <MSidebarShortcuts stacked>
+        <MSidebarShortcutItem
+          v-for="(item, index) in shortcutItems"
+          :key="index"
+          v-bind="item"
+        />
+      </MSidebarShortcuts>
+    </template>
+
+    <template #nav>
+      <template v-for="(item, index) in navigationItems" :key="index">
+        <MSidebarExpandableItem
+          v-if="item.items"
+          menu-label="Sublist menu label"
+          :label="item.label"
+          :icon="item.icon"
+        >
+          <MSidebarNavItem
+            v-for="(subItem, subIndex) in item.items"
+            :key="subIndex"
+            v-bind="subItem"
+            :active="active === `subNav-${subIndex}`"
+            @click="active = `subNav-${subIndex}`"
+          />
+        </MSidebarExpandableItem>
+
+        <MSidebarNavItem
+          v-else
+          v-bind="item"
+          :active="active === `nav-${index}`"
+          @click="active = `nav-${index}`"
+        />
+      </template>
+    </template>
+
+    <template #footer>
+      <MSidebarFooter
+        title="Dieter Rams"
+        subtitle="Industrial designer"
+        href="#"
+        avatar="/images/Avatar.png"
+        @log-out="emit('log-out')"
+      >
+        <MSidebarNavItem
+          v-for="(item, index) in footerMenuItems"
+          :key="index"
+          v-bind="item"
+          :active="active === `footer-${index}`"
+          @click="active = `footer-${index}`"
+        />
+      </MSidebarFooter>
+    </template>
+  </MSidebar>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  Coffee24,
+  Course24,
+  Sample24,
+  Release24,
+  Palette24,
+  Pantone24,
+  Admin24,
+} from '@mozaic-ds/icons-vue';
+
+import MSidebar from '../MSidebar.vue';
+import MSidebarExpandableItem from '../../sidebarexpandableitem/MSidebarExpandableItem.vue';
+import MSidebarFooter from '../../sidebarfooter/MSidebarFooter.vue';
+import MSidebarHeader from '../../sidebarheader/MSidebarHeader.vue';
+import MSidebarNavItem from '../../sidebarnavitem/MSidebarNavItem.vue';
+import MSidebarShortcutItem from '../../sidebarshortcutitem/MSidebarShortcutItem.vue';
+import MSidebarShortcuts from '../../sidebarshortcuts/MSidebarShortcuts.vue';
+
+const emit = defineEmits(['close', 'update:modelValue', 'log-out']);
+
+const expanded = ref(true);
+
+const active = ref('');
+
+const shortcutItems = [
+  { label: 'Shortcut 01', icon: Coffee24, href: '#' },
+  { label: 'Shortcut 02', icon: Course24, href: '#' },
+];
+
+const navigationItems = [
+  { label: 'Get Started', href: '#', icon: Release24 },
+  {
+    label: 'Design Tokens',
+    icon: Sample24,
+    items: [
+      { label: 'Subsection menu label 1', href: '#', locked: true },
+      { label: 'Subsection menu label 2', href: '#', external: true },
+      { label: 'Subsection menu label 2', href: '#' },
+      { label: 'Subsection menu label 2', href: '#' },
+    ],
+  },
+  { label: 'Styles', href: '#', icon: Palette24 },
+  { label: 'Components', href: '#', icon: Pantone24 },
+];
+
+const footerMenuItems = [
+  { label: 'Action 01', icon: Admin24, href: '#' },
+  { label: 'Action 02', icon: Admin24, href: '#' },
+  { label: 'Action 03', icon: Admin24, href: '#' },
+  { label: 'Action 04', icon: Admin24, href: '#' },
+];
+</script>

package/src/components/sidebar/stories/README.md

@@ -0,0 +1,27 @@
+# WithSingleLevel.stories
+
+
+
+## Dependencies
+
+### Depends on
+
+- [MSidebar](..)
+- [MSidebarFooter](../../sidebarfooter)
+- [MSidebarHeader](../../sidebarheader)
+- [MSidebarNavItem](../../sidebarnavitem)
+- [MSidebarShortcutItem](../../sidebarshortcutitem)
+- [MSidebarShortcuts](../../sidebarshortcuts)
+
+### Graph
+
+```mermaid
+graph TD;
+  WithSingleLevel.stories --> MSidebar
+  WithSingleLevel.stories --> MSidebarFooter
+  WithSingleLevel.stories --> MSidebarHeader
+  WithSingleLevel.stories --> MSidebarNavItem
+  WithSingleLevel.stories --> MSidebarShortcutItem
+  WithSingleLevel.stories --> MSidebarShortcuts
+style WithSingleLevel.stories fill:#008240,stroke:#333,stroke-width:4px
+```

package/src/components/sidebar/stories/WithExpandOnly.stories.vue

@@ -0,0 +1,112 @@
+<template>
+  <MSidebar
+    v-model="expanded"
+    @update:model-value="emit('update:modelValue')"
+    @close="emit('close')"
+  >
+    <template #header>
+      <MSidebarHeader title="Adeo Design System" logo="/logo.svg" />
+    </template>
+
+    <template #shortcuts>
+      <MSidebarShortcuts>
+        <MSidebarShortcutItem
+          v-for="(item, index) in shortcutItems"
+          :key="index"
+          v-bind="item"
+        />
+      </MSidebarShortcuts>
+    </template>
+
+    <template #nav>
+      <template v-for="(item, index) in navigationItems" :key="index">
+        <MSidebarExpandableItem
+          v-if="item.items"
+          menu-label="Sublist menu label"
+          :label="item.label"
+          :icon="item.icon"
+        >
+          <MSidebarNavItem
+            v-for="(subItem, subIndex) in item.items"
+            :key="subIndex"
+            v-bind="subItem"
+            :active="active === `subNav-${subIndex}`"
+            @click="active = `subNav-${subIndex}`"
+          />
+        </MSidebarExpandableItem>
+
+        <MSidebarNavItem
+          v-else
+          v-bind="item"
+          :active="active === `nav-${index}`"
+          @click="active = `nav-${index}`"
+        />
+      </template>
+    </template>
+
+    <template #footer>
+      <MSidebarFooter @log-out="emit('log-out')">
+        <MSidebarNavItem
+          v-for="(item, index) in footerMenuItems"
+          :key="index"
+          v-bind="item"
+          :active="active === `footer-${index}`"
+          @click="active = `footer-${index}`"
+        />
+      </MSidebarFooter>
+    </template>
+  </MSidebar>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  Coffee24,
+  Course24,
+  Sample24,
+  Release24,
+  Palette24,
+  Pantone24,
+  Admin24,
+} from '@mozaic-ds/icons-vue';
+
+import MSidebar from '../MSidebar.vue';
+import MSidebarExpandableItem from '../../sidebarexpandableitem/MSidebarExpandableItem.vue';
+import MSidebarFooter from '../../sidebarfooter/MSidebarFooter.vue';
+import MSidebarHeader from '../../sidebarheader/MSidebarHeader.vue';
+import MSidebarNavItem from '../../sidebarnavitem/MSidebarNavItem.vue';
+import MSidebarShortcutItem from '../../sidebarshortcutitem/MSidebarShortcutItem.vue';
+import MSidebarShortcuts from '../../sidebarshortcuts/MSidebarShortcuts.vue';
+
+const emit = defineEmits(['close', 'update:modelValue', 'log-out']);
+
+const expanded = ref(true);
+
+const active = ref('');
+
+const shortcutItems = [
+  { label: 'Shortcut 01', icon: Coffee24, href: '#' },
+  { label: 'Shortcut 02', icon: Course24, href: '#' },
+];
+
+const navigationItems = [
+  { label: 'Get Started', href: '#', icon: Release24 },
+  {
+    label: 'Design Tokens',
+    icon: Sample24,
+    items: [
+      { label: 'Subsection menu label 1', href: '#', locked: true },
+      { label: 'Subsection menu label 2', href: '#', external: true },
+    ],
+  },
+  { label: 'Styles', href: '#', icon: Palette24 },
+  { label: 'Components', href: '#', icon: Pantone24 },
+];
+
+const footerMenuItems = [
+  { label: 'Action 01', icon: Admin24, href: '#' },
+  { label: 'Action 02', icon: Admin24, href: '#' },
+  { label: 'Action 03', icon: Admin24, href: '#' },
+  { label: 'Action 04', icon: Admin24, href: '#' },
+];
+</script>