@fiscozen/card-list 1.0.0

package/dist/src/components/FzCardTitle.vue.d.ts

@@ -0,0 +1,13 @@
+import { FzCardTitleProps } from './types';
+
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<__VLS_TypePropsToRuntimeProps<FzCardTitleProps>>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<__VLS_TypePropsToRuntimeProps<FzCardTitleProps>>> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

package/dist/src/components/types.d.ts

@@ -0,0 +1,34 @@
+import { FzActionLinkProps, FzActionProps } from '@fiscozen/action';
+import { FzBadgeTone } from '@fiscozen/badge';
+
+export type FzCardBadge = {
+    text: string;
+    tone: FzBadgeTone;
+};
+export interface FzCardTitleProps {
+    showIndicator?: boolean;
+    title: string;
+    titleId?: string;
+}
+export interface FzCardHeaderProps extends FzCardTitleProps {
+    hasTitleOnly?: boolean;
+    value?: string;
+}
+export interface FzCardListFooterProps {
+    descriptions?: string[];
+}
+export interface FzCardNoActionProps extends FzCardHeaderProps, FzCardListFooterProps {
+    badge?: FzCardBadge;
+}
+export interface FzCardSingleActionProps extends FzCardHeaderProps, FzCardListFooterProps, FzCardNoActionProps {
+    action?: FzActionLinkProps;
+}
+export interface FzCardSingleActionEmits {
+    (event: "fzaction:click", action: FzActionLinkProps): void;
+}
+export interface FzCardMultiActionsProps extends FzCardHeaderProps, FzCardListFooterProps, FzCardNoActionProps {
+    actions: FzActionProps[];
+}
+export interface FzCardMultiActionsEmits {
+    (event: "fzaction:click", actionIndex: number, action: FzActionProps): void;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { default as FzCardList } from './FzCardList.vue';
+export { default as FzCardListItem } from './FzCardListItem.vue';
+export type * from './types';

package/dist/src/types.d.ts

@@ -0,0 +1,64 @@
+import { FzActionProps } from '@fiscozen/action';
+import { FzBadgeTone } from '@fiscozen/badge';
+
+export type ActionsMode = "none" | "link" | "actions";
+export interface FzCardListItemProps {
+    /**
+     * Badge displayed inside the card at the top-left.
+     * When omitted, no badge is displayed.
+     */
+    badge?: {
+        /**
+         * Text of the badge.
+         */
+        text: string;
+        /**
+         * Tone of the badge.
+         */
+        tone: FzBadgeTone;
+    };
+    /**
+     * Main title of the item, displayed in bold.
+     */
+    title: string;
+    /**
+     * Value displayed on the right side of the title row (e.g. "0,00 €").
+     */
+    value?: string;
+    /**
+     * Description lines rendered below the title row.
+     */
+    descriptions?: string[];
+    /**
+     * Whether to show the indicator icon before the title.
+     */
+    showIndicator?: boolean;
+    /**
+     * Row actions. When omitted or `[]`, no trailing control is shown. With one item, an arrow button is shown; with more than one, an ellipsis opens a dropdown.
+     */
+    actions?: FzActionProps[];
+}
+export interface FzCardListItemEmits {
+    /**
+     * Emitted when a row action is chosen: single-arrow click, or an item from the overflow dropdown.
+     */
+    (event: "fzaction:click", actionIndex: number, action: FzActionProps): void;
+}
+/**
+ * A single item in the card list when using data-driven rendering.
+ * Maps directly to FzCardListItemProps.
+ */
+export type FzCardListItem = FzCardListItemProps;
+export type FzCardListProps = {
+    /**
+     * Array of card item data for data-driven rendering.
+     * Each item is rendered as an FzCardListItem.
+     */
+    items: FzCardListItem[];
+};
+export interface FzCardListEmits {
+    /**
+     * Emitted when a row action is triggered for an item built from `items`.
+     */
+    (event: "fzaction:click", itemIndex: number, actionIndex: number, action: FzActionProps): void;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@fiscozen/card-list",
+  "version": "1.0.0",
+  "description": "Design System CardList component",
+  "main": "src/index.ts",
+  "type": "module",
+  "keywords": [],
+  "author": "Francesca Vago",
+  "dependencies": {
+    "@fiscozen/action": "3.0.0",
+    "@fiscozen/button": "3.0.0",
+    "@fiscozen/divider": "1.0.1",
+    "@fiscozen/container": "0.4.2",
+    "@fiscozen/badge": "3.0.0",
+    "@fiscozen/dropdown": "1.0.6"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^3.4.1",
+    "vue": "^3.4.13",
+    "@fiscozen/icons": "^1.0.1"
+  },
+  "devDependencies": {
+    "@rushstack/eslint-patch": "^1.3.3",
+    "@types/jsdom": "^21.1.6",
+    "@types/node": "^18.19.3",
+    "@vitejs/plugin-vue": "^4.5.2",
+    "@vitest/coverage-v8": "^1.2.1",
+    "@vue/test-utils": "^2.4.3",
+    "@vue/tsconfig": "^0.5.0",
+    "eslint": "^8.49.0",
+    "jsdom": "^23.0.1",
+    "prettier": "^3.0.3",
+    "typescript": "~5.3.0",
+    "vite": "^5.0.10",
+    "vite-plugin-dts": "^3.8.3",
+    "vitest": "^1.2.0",
+    "vue-tsc": "^1.8.25",
+    "@fiscozen/eslint-config": "^0.1.0",
+    "@fiscozen/prettier-config": "^0.1.0",
+    "@fiscozen/tsconfig": "^0.1.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "coverage": "vitest run --coverage",
+    "format": "prettier --write src/",
+    "test:unit": "vitest run",
+    "build": "vue-tsc && vite build"
+  }
+}

package/src/FzCardList.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+/**
+ * FzCardList Component
+ *
+ * A layout container that renders a list of FzCardListItem components either from
+ * a data array (via the `items` prop).
+ *
+ *
+ * @component
+ * @example
+ * <FzCardList title="My List" :items="listItems" />
+ *
+ * @example
+ * <FzCardList>
+ *   <FzCardListItem title="Item 1" amount="0,00 €" />
+ *   <FzCardListItem title="Item 2" amount="1,00 €" />
+ * </FzCardList>
+ */
+import FzCardListItem from './FzCardListItem.vue';
+import type { FzActionProps } from '@fiscozen/action';
+import { FzCardListProps, FzCardListEmits } from './types';
+import { FzContainer } from '@fiscozen/container';
+
+defineProps<FzCardListProps>();
+
+const emit = defineEmits<FzCardListEmits>();
+
+function emitItemActionClick(
+  itemIndex: number,
+  actionIndex: number,
+  action: FzActionProps,
+) {
+  emit('fzaction:click', itemIndex, actionIndex, action);
+}
+</script>
+
+<template>
+  <FzContainer gap="xs">
+    <FzCardListItem
+      v-for="(item, index) in items"
+      :key="index"
+      :badge="item.badge"
+      :title="item.title"
+      :value="item.value"
+      :descriptions="item.descriptions"
+      :showIndicator="item.showIndicator"
+      :actions="item.actions"
+      @fzaction:click="
+        (actionIndex, action) =>
+          emitItemActionClick(index, actionIndex, action)
+      "
+    />
+  </FzContainer>
+</template>

package/src/FzCardListItem.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+/**
+ * FzCardListItem Component
+ *
+ * A list item row used inside FzCardList.
+ * Displays an optional badge, row actions (single arrow, or action dropdown),
+ * a status indicator dot, a bold title with an optional amount on the right, and optional description lines.
+ *
+ * @component
+ * @example
+ * <FzCardListItem
+ *   badge="Text badge"
+ *   title="Title"
+ *   amount="0,00 €"
+ *   :descriptions="['Description 1', 'Description 2']"
+ *   @fzaction:click="onActionClick"
+ * />
+ */
+import { computed } from "vue";
+import type {
+  ActionsMode,
+  FzCardListItemProps,
+  FzCardListItemEmits,
+} from "./types";
+import type { FzActionLinkProps, FzActionProps } from "@fiscozen/action";
+import FzCardActionLink from "./components/FzCardActionLink.vue";
+import FzCardMultiActions from "./components/FzCardMultiActions.vue";
+import FzCardNoAction from "./components/FzCardNoAction.vue";
+
+const props = defineProps<FzCardListItemProps>();
+
+const emit = defineEmits<FzCardListItemEmits>();
+
+const actionsMode = computed<ActionsMode>(() => {
+  if (!props.actions?.length) return "none";
+  if (props.actions.length === 1 && props.actions[0].type === "link") return "link";
+  return "actions";
+});
+
+</script>
+
+<template>
+  <FzCardNoAction
+    v-if="actionsMode === 'none'"
+    :badge="badge"
+    :title="title"
+    :show-indicator="showIndicator"
+    :value="value"
+    :descriptions="descriptions"
+  />
+  <FzCardActionLink
+    v-else-if="actionsMode === 'link'"
+    :badge="badge"
+    :title="title"
+    :show-indicator="showIndicator"
+    :value="value"
+    :descriptions="descriptions"
+    :action="actions?.[0] as FzActionLinkProps"
+    @fzaction:click="(action) => emit('fzaction:click', 0, action as FzActionProps)"
+  />
+  <FzCardMultiActions
+    v-else
+    :badge="badge"
+    :title="title"
+    :show-indicator="showIndicator"
+    :value="value"
+    :descriptions="descriptions"
+    :actions="actions as FzActionProps[]"
+    @fzaction:click="(index, action) => emit('fzaction:click', index, action)"
+  />
+</template>

package/src/__tests__/FzCardList.spec.ts

@@ -0,0 +1,322 @@
+import { mount, config } from "@vue/test-utils";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { FzActionProps } from "@fiscozen/action";
+import FzCardList from "../FzCardList.vue";
+
+const sampleAction: FzActionProps = {
+  type: "action",
+  variant: "textLeft",
+  label: "Go",
+};
+
+const linkAction = { type: "link" as const, to: "/" };
+
+beforeEach(() => {
+  // Mock IntersectionObserver for FzFloating / dropdown (not in jsdom)
+  global.IntersectionObserver = class IntersectionObserver {
+    constructor() {}
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  } as any;
+
+  config.global.directives = {
+    bold: () => {},
+    color: () => {},
+    small: () => {},
+  };
+
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    configurable: true,
+    value: vi.fn().mockImplementation((query) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+});
+
+describe("FzCardList", () => {
+  describe("Rendering", () => {
+    it("should render with empty items", async () => {
+      const wrapper = mount(FzCardList, {
+        props: { items: [] },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.exists()).toBe(true);
+      expect(
+        wrapper.findAllComponents({ name: "FzCardListItem" }),
+      ).toHaveLength(0);
+      expect(wrapper.element.children.length).toBe(0);
+    });
+
+    it("should not render a title heading (title prop is not used by the template)", async () => {
+      const wrapper = mount(FzCardList, {
+        props: { title: "My Card List", items: [] },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.find("h2").exists()).toBe(false);
+    });
+
+    it("does not render default slot content (list is driven by items only)", async () => {
+      const wrapper = mount(FzCardList, {
+        props: { items: [] },
+        slots: {
+          default: '<div class="custom-item">Custom Item</div>',
+        },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.html()).not.toContain("Custom Item");
+    });
+
+    it("should render FzCardListItem for each item in items array", async () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          items: [
+            { title: "Item 1" },
+            { title: "Item 2" },
+            { title: "Item 3" },
+          ],
+        },
+      });
+      await wrapper.vm.$nextTick();
+      const items = wrapper.findAllComponents({ name: "FzCardListItem" });
+      expect(items).toHaveLength(3);
+    });
+
+    it("should render item title text", async () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          items: [{ title: "Hello World" }],
+        },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.html()).toContain("Hello World");
+    });
+
+    it("should not render default slot when items is an empty array", async () => {
+      const wrapper = mount(FzCardList, {
+        props: { items: [] },
+        slots: {
+          default: '<div class="slot-content">Slot Content</div>',
+        },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.html()).not.toContain("Slot Content");
+    });
+  });
+
+  describe("Props", () => {
+    describe("items prop", () => {
+      it("should pass title to FzCardListItem", async () => {
+        const wrapper = mount(FzCardList, {
+          props: { items: [{ title: "Item Title" }] },
+        });
+        await wrapper.vm.$nextTick();
+        const item = wrapper.findComponent({ name: "FzCardListItem" });
+        expect(item.props("title")).toBe("Item Title");
+      });
+
+      it("should pass value to FzCardListItem", async () => {
+        const wrapper = mount(FzCardList, {
+          props: { items: [{ title: "Item", value: "1.234,56 €" }] },
+        });
+        await wrapper.vm.$nextTick();
+        const item = wrapper.findComponent({ name: "FzCardListItem" });
+        expect(item.props("value")).toBe("1.234,56 €");
+      });
+
+      it("should pass badge to FzCardListItem", async () => {
+        const badge = { text: "New", tone: "dark" as const };
+        const wrapper = mount(FzCardList, {
+          props: { items: [{ title: "Item", badge }] },
+        });
+        await wrapper.vm.$nextTick();
+        const item = wrapper.findComponent({ name: "FzCardListItem" });
+        expect(item.props("badge")).toEqual(badge);
+      });
+
+      it("should pass descriptions to FzCardListItem", async () => {
+        const wrapper = mount(FzCardList, {
+          props: {
+            items: [{ title: "Item", descriptions: ["Line 1", "Line 2"] }],
+          },
+        });
+        await wrapper.vm.$nextTick();
+        const item = wrapper.findComponent({ name: "FzCardListItem" });
+        expect(item.props("descriptions")).toEqual(["Line 1", "Line 2"]);
+      });
+
+      it("should pass showIndicator to FzCardListItem", async () => {
+        const wrapper = mount(FzCardList, {
+          props: { items: [{ title: "Item", showIndicator: true }] },
+        });
+        await wrapper.vm.$nextTick();
+        const item = wrapper.findComponent({ name: "FzCardListItem" });
+        expect(item.props("showIndicator")).toBe(true);
+      });
+
+      it("should pass actions to FzCardListItem", async () => {
+        const actions = [
+          { type: "action" as const, variant: "textLeft" as const, label: "A" },
+        ];
+        const wrapper = mount(FzCardList, {
+          props: { items: [{ title: "Item", actions }] },
+        });
+        await wrapper.vm.$nextTick();
+        const item = wrapper.findComponent({ name: "FzCardListItem" });
+        expect(item.props("actions")).toEqual(actions);
+      });
+    });
+  });
+
+  describe("Events", () => {
+    it("should emit fzaction:click with item index when link-action arrow is clicked", async () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          items: [
+            { title: "Item 0", actions: [linkAction] },
+            { title: "Item 1", actions: [linkAction] },
+          ],
+        },
+      });
+      await wrapper.vm.$nextTick();
+
+      const items = wrapper.findAllComponents({ name: "FzCardListItem" });
+      await items[1].get('[role="button"]').trigger("click");
+
+      expect(wrapper.emitted("fzaction:click")).toBeTruthy();
+      expect(wrapper.emitted("fzaction:click")![0]).toEqual([
+        1,
+        0,
+        linkAction,
+      ]);
+    });
+
+    it("should emit fzaction:click with index 0 when first item link-action arrow is clicked", async () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          items: [{ title: "Item 0", actions: [linkAction] }],
+        },
+      });
+      await wrapper.vm.$nextTick();
+
+      const item = wrapper.findComponent({ name: "FzCardListItem" });
+      await item.get('[role="button"]').trigger("click");
+
+      expect(wrapper.emitted("fzaction:click")).toBeTruthy();
+      expect(wrapper.emitted("fzaction:click")![0]).toEqual([
+        0,
+        0,
+        linkAction,
+      ]);
+    });
+
+    it("should emit fzaction:click with item index and action payload", async () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          items: [
+            { title: "A" },
+            {
+              title: "B",
+              actions: [sampleAction, { ...sampleAction, label: "B" }],
+            },
+          ],
+        },
+      });
+      await wrapper.vm.$nextTick();
+
+      const items = wrapper.findAllComponents({ name: "FzCardListItem" });
+      await items[1].vm.$emit("fzaction:click", 0, sampleAction);
+
+      expect(wrapper.emitted("fzaction:click")).toBeTruthy();
+      expect(wrapper.emitted("fzaction:click")![0]).toEqual([
+        1,
+        0,
+        sampleAction,
+      ]);
+    });
+  });
+
+  describe("Accessibility", () => {
+    it("should wrap items in a container element", async () => {
+      const wrapper = mount(FzCardList, {
+        props: { items: [{ title: "A" }] },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.findComponent({ name: "FzCardListItem" }).exists()).toBe(
+        true,
+      );
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should render a FzCardListItem even with only a title", async () => {
+      const wrapper = mount(FzCardList, {
+        props: { items: [{ title: "Minimal" }] },
+      });
+      await wrapper.vm.$nextTick();
+      const item = wrapper.findComponent({ name: "FzCardListItem" });
+      expect(item.exists()).toBe(true);
+    });
+
+    it("should handle a large number of items", async () => {
+      const items = Array.from({ length: 20 }, (_, i) => ({
+        title: `Item ${i}`,
+      }));
+      const wrapper = mount(FzCardList, { props: { items } });
+      await wrapper.vm.$nextTick();
+      const rendered = wrapper.findAllComponents({ name: "FzCardListItem" });
+      expect(rendered).toHaveLength(20);
+    });
+
+    it("should render list items when title prop is also provided (title is unused in template)", async () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          title: "My List",
+          items: [{ title: "Item 1" }],
+        },
+      });
+      await wrapper.vm.$nextTick();
+      expect(wrapper.find("h2").exists()).toBe(false);
+      expect(
+        wrapper.findAllComponents({ name: "FzCardListItem" }),
+      ).toHaveLength(1);
+    });
+  });
+
+  describe("Snapshots", () => {
+    it("should match snapshot - default state", () => {
+      const wrapper = mount(FzCardList, {
+        props: { items: [] },
+      });
+      expect(wrapper.html()).toMatchSnapshot();
+    });
+
+    it("should match snapshot - with items", () => {
+      const wrapper = mount(FzCardList, {
+        props: {
+          items: [
+            {
+              title: "Item 1",
+              value: "1.200,00 €",
+              showIndicator: true,
+            },
+            {
+              title: "Item 2",
+              badge: { text: "New", tone: "dark" },
+              descriptions: ["Due date: 2024-03-01"],
+            },
+          ],
+        },
+      });
+      expect(wrapper.html()).toMatchSnapshot();
+    });
+  });
+});