@gxp-dev/mod-ui 2.0.0

package/src/components/compositions/elements/display/CarouselDisplay.vue

@@ -0,0 +1,209 @@
+<script setup lang="ts">
+/**
+ * Props-driven carousel display.
+ *
+ * Wraps `embla-carousel-vue` to render a slideshow of image / html / text
+ * slides. Read-only — no `modelValue`. Supports looping, autoplay (via a
+ * lightweight `setInterval`, since `embla-carousel-autoplay` is not a
+ * dependency here), prev/next arrows, and dot indicators.
+ *
+ *   <CarouselDisplay :slides="[{ src: '/a.jpg', alt: 'A' }, { src: '/b.jpg' }]" />
+ */
+import { computed, onBeforeUnmount, ref, watch } from "vue"
+import emblaCarouselVue from "embla-carousel-vue"
+import { ChevronLeft, ChevronRight } from "lucide-vue-next"
+import { cn } from "@/lib/utils"
+
+export interface CarouselSlide {
+  src?: string
+  alt?: string
+  caption?: string
+  html?: string
+}
+
+export interface CarouselDisplayProps {
+  slides?: CarouselSlide[]
+  loop?: boolean
+  autoplay?: boolean
+  autoplayDelayMs?: number
+  showIndicators?: boolean
+  showArrows?: boolean
+  classList?: string[] | string
+}
+
+const props = withDefaults(defineProps<CarouselDisplayProps>(), {
+  slides: () => [],
+  loop: true,
+  autoplay: false,
+  autoplayDelayMs: 5000,
+  showIndicators: true,
+  showArrows: true,
+})
+
+const [emblaRef, emblaApi] = emblaCarouselVue(
+  computed(() => ({ loop: props.loop })),
+)
+
+const selectedIndex = ref<number>(0)
+const slideCount = computed<number>(() => props.slides.length)
+
+function onSelect(): void {
+  const api = emblaApi.value
+  if (!api) {
+    return
+  }
+  selectedIndex.value = api.selectedScrollSnap()
+}
+
+watch(emblaApi, (api) => {
+  if (!api) {
+    return
+  }
+  onSelect()
+  api.on("select", onSelect)
+  api.on("reInit", onSelect)
+})
+
+let autoplayTimer: ReturnType<typeof setInterval> | null = null
+
+function clearAutoplay(): void {
+  if (autoplayTimer !== null) {
+    clearInterval(autoplayTimer)
+    autoplayTimer = null
+  }
+}
+
+function startAutoplay(): void {
+  clearAutoplay()
+  if (!props.autoplay || slideCount.value <= 1) {
+    return
+  }
+  autoplayTimer = setInterval(() => {
+    emblaApi.value?.scrollNext()
+  }, props.autoplayDelayMs)
+}
+
+watch(
+  () => [props.autoplay, props.autoplayDelayMs, slideCount.value] as const,
+  () => {
+    startAutoplay()
+  },
+  { immediate: true },
+)
+
+onBeforeUnmount(() => {
+  clearAutoplay()
+})
+
+function scrollPrev(): void {
+  emblaApi.value?.scrollPrev()
+}
+
+function scrollNext(): void {
+  emblaApi.value?.scrollNext()
+}
+
+function scrollTo(index: number): void {
+  emblaApi.value?.scrollTo(index)
+}
+
+const rootClass = computed<string>(() => {
+  const cl = props.classList
+  if (!cl) {
+    return ""
+  }
+  return Array.isArray(cl) ? cl.join(" ") : cl
+})
+</script>
+
+<template>
+  <div
+    :class="cn('relative w-full overflow-hidden', rootClass)"
+    data-testid="carousel-display"
+  >
+    <div
+      v-if="slideCount === 0"
+      class="flex h-32 w-full items-center justify-center rounded border border-dashed bg-muted text-sm text-muted-foreground"
+      data-testid="carousel-display-empty"
+    >
+      No slides
+    </div>
+    <template v-else>
+      <div ref="emblaRef" class="overflow-hidden" data-testid="carousel-viewport">
+        <div class="flex">
+          <div
+            v-for="(slide, index) in slides"
+            :key="index"
+            class="min-w-0 flex-[0_0_100%]"
+            data-testid="carousel-slide"
+          >
+            <img
+              v-if="slide.src"
+              :src="slide.src"
+              :alt="slide.alt ?? ''"
+              class="block h-auto w-full rounded"
+              loading="lazy"
+            >
+            <div
+              v-else-if="slide.html"
+              class="h-full w-full"
+              v-html="slide.html"
+            />
+            <div
+              v-else
+              class="flex h-full w-full items-center justify-center p-6 text-center text-sm"
+            >
+              {{ slide.caption ?? "" }}
+            </div>
+            <p
+              v-if="slide.src && slide.caption"
+              class="mt-2 text-sm text-muted-foreground"
+              data-testid="carousel-slide-caption"
+            >
+              {{ slide.caption }}
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <template v-if="showArrows && slideCount > 1">
+        <button
+          type="button"
+          class="absolute left-2 top-1/2 -translate-y-1/2 inline-flex h-8 w-8 items-center justify-center rounded-full bg-background/70 text-foreground shadow ring-1 ring-border hover:bg-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          aria-label="Previous slide"
+          data-testid="carousel-prev"
+          @click="scrollPrev"
+        >
+          <ChevronLeft class="size-4" />
+        </button>
+        <button
+          type="button"
+          class="absolute right-2 top-1/2 -translate-y-1/2 inline-flex h-8 w-8 items-center justify-center rounded-full bg-background/70 text-foreground shadow ring-1 ring-border hover:bg-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          aria-label="Next slide"
+          data-testid="carousel-next"
+          @click="scrollNext"
+        >
+          <ChevronRight class="size-4" />
+        </button>
+      </template>
+
+      <div
+        v-if="showIndicators && slideCount > 1"
+        class="mt-2 flex items-center justify-center gap-1.5"
+        data-testid="carousel-indicators"
+      >
+        <button
+          v-for="(_, index) in slides"
+          :key="index"
+          type="button"
+          class="h-2 w-2 rounded-full bg-muted-foreground/40 transition-colors hover:bg-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          :class="index === selectedIndex ? 'bg-primary' : ''"
+          :aria-label="`Go to slide ${index + 1}`"
+          :aria-current="index === selectedIndex ? 'true' : undefined"
+          data-testid="carousel-indicator"
+          @click="scrollTo(index)"
+        />
+      </div>
+    </template>
+  </div>
+</template>

package/src/components/compositions/elements/display/ChartDisplay.stories.ts

@@ -0,0 +1,116 @@
+import type { ChartData } from "chart.js"
+import type { Meta, StoryObj } from "@storybook/vue3"
+import ChartDisplay from "./ChartDisplay.vue"
+
+const lineData: ChartData<"line"> = {
+  labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
+  datasets: [
+    {
+      label: "Revenue",
+      data: [12, 19, 14, 22, 28, 31],
+      borderColor: "hsl(var(--primary))",
+      backgroundColor: "hsl(var(--primary) / 0.2)",
+      tension: 0.35,
+      fill: true,
+    },
+  ],
+}
+
+const barData: ChartData<"bar"> = {
+  labels: ["Q1", "Q2", "Q3", "Q4"],
+  datasets: [
+    {
+      label: "Tickets",
+      data: [120, 190, 145, 230],
+      backgroundColor: "hsl(var(--primary) / 0.8)",
+    },
+  ],
+}
+
+const pieData: ChartData<"pie"> = {
+  labels: ["GA", "VIP", "Press", "Comp"],
+  datasets: [
+    {
+      data: [60, 20, 8, 12],
+      backgroundColor: [
+        "hsl(var(--primary))",
+        "hsl(var(--success))",
+        "hsl(var(--warning))",
+        "hsl(var(--info))",
+      ],
+    },
+  ],
+}
+
+const radarData: ChartData<"radar"> = {
+  labels: ["Speed", "Accuracy", "UX", "Reliability", "Security"],
+  datasets: [
+    {
+      label: "v1",
+      data: [3, 4, 2, 4, 3],
+      borderColor: "hsl(var(--muted-foreground))",
+      backgroundColor: "hsl(var(--muted) / 0.4)",
+    },
+    {
+      label: "v2",
+      data: [4, 5, 5, 4, 4],
+      borderColor: "hsl(var(--primary))",
+      backgroundColor: "hsl(var(--primary) / 0.2)",
+    },
+  ],
+}
+
+const meta = {
+  title: "Compositions/Elements/Display/ChartDisplay",
+  component: ChartDisplay,
+  tags: ["autodocs"],
+  args: {
+    chartType: "line",
+    data: lineData as ChartData,
+    height: 320,
+  },
+  decorators: [
+    () => ({ template: '<div class="max-w-2xl p-4"><story /></div>' }),
+  ],
+} satisfies Meta<typeof ChartDisplay>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { chartType: "line", data: lineData as ChartData },
+}
+
+export const Bar: Story = {
+  args: { chartType: "bar", data: barData as ChartData },
+}
+
+export const Pie: Story = {
+  args: { chartType: "pie", data: pieData as ChartData, height: 360 },
+}
+
+export const Doughnut: Story = {
+  args: { chartType: "doughnut", data: pieData as ChartData, height: 360 },
+}
+
+export const Radar: Story = {
+  args: { chartType: "radar", data: radarData as ChartData, height: 360 },
+}
+
+export const Showcase: Story = {
+  args: {} as never,
+  render: () => ({
+    components: { ChartDisplay },
+    setup() {
+      return { lineData, barData, pieData, radarData }
+    },
+    template: `
+      <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+        <ChartDisplay chart-type="line" :data="lineData" :height="260" />
+        <ChartDisplay chart-type="bar" :data="barData" :height="260" />
+        <ChartDisplay chart-type="pie" :data="pieData" :height="260" />
+        <ChartDisplay chart-type="radar" :data="radarData" :height="260" />
+      </div>
+    `,
+  }),
+}

package/src/components/compositions/elements/display/ChartDisplay.test.ts

@@ -0,0 +1,135 @@
+import type { ChartData } from "chart.js"
+import { describe, expect, it } from "vitest"
+import { mount } from "@vue/test-utils"
+import ChartDisplay from "./ChartDisplay.vue"
+
+const sampleData: ChartData<"line"> = {
+  labels: ["Jan", "Feb", "Mar"],
+  datasets: [
+    {
+      label: "Revenue",
+      data: [10, 20, 30],
+    },
+  ],
+}
+
+const barData: ChartData<"bar"> = {
+  labels: ["A", "B"],
+  datasets: [{ label: "Q", data: [1, 2] }],
+}
+
+const pieData: ChartData<"pie"> = {
+  labels: ["X", "Y"],
+  datasets: [{ data: [1, 2] }],
+}
+
+describe("ChartDisplay", () => {
+  it("mounts a line chart by default", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: { data: sampleData as ChartData },
+    })
+    const root = wrapper.find("[data-testid='chart-display']")
+    expect(root.exists()).toBe(true)
+    expect(root.attributes("data-chart-type")).toBe("line")
+    expect(root.find("canvas").exists()).toBe(true)
+  })
+
+  it("mounts a bar chart when chartType is bar", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: { chartType: "bar", data: barData as ChartData },
+    })
+    expect(
+      wrapper
+        .find("[data-testid='chart-display']")
+        .attributes("data-chart-type"),
+    ).toBe("bar")
+    expect(wrapper.find("canvas").exists()).toBe(true)
+  })
+
+  it("mounts a pie chart when chartType is pie", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: { chartType: "pie", data: pieData as ChartData },
+    })
+    expect(
+      wrapper
+        .find("[data-testid='chart-display']")
+        .attributes("data-chart-type"),
+    ).toBe("pie")
+    expect(wrapper.find("canvas").exists()).toBe(true)
+  })
+
+  it("mounts a doughnut chart when chartType is doughnut", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: { chartType: "doughnut", data: pieData as ChartData },
+    })
+    expect(
+      wrapper
+        .find("[data-testid='chart-display']")
+        .attributes("data-chart-type"),
+    ).toBe("doughnut")
+    expect(wrapper.find("canvas").exists()).toBe(true)
+  })
+
+  it("forwards the data prop to the underlying chart component", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: { data: sampleData as ChartData },
+    })
+    const chart = wrapper.findComponent({ name: "LineChart" })
+      ?? wrapper.findAllComponents({ name: "Line" })[0]
+      ?? wrapper.findAllComponents("Line" as unknown as never)[0]
+    // Fallback: the canvas always exists when the chart mounted successfully
+    expect(wrapper.find("canvas").exists()).toBe(true)
+    // And vue-chartjs forwards the data prop verbatim
+    if (chart && chart.exists()) {
+      expect(chart.props("data")).toEqual(sampleData)
+    }
+  })
+
+  it("merges responsive/maintainAspectRatio defaults with user options", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: {
+        data: sampleData as ChartData,
+        options: { plugins: { legend: { display: false } } },
+      },
+    })
+    expect(wrapper.find("canvas").exists()).toBe(true)
+  })
+
+  it("applies classList to the wrapper", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: { data: sampleData as ChartData, classList: "stub-class" },
+    })
+    expect(
+      wrapper.find("[data-testid='chart-display']").attributes("class"),
+    ).toContain("stub-class")
+  })
+
+  it("applies width and height to the wrapper as inline style", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: {
+        data: sampleData as ChartData,
+        width: 640,
+        height: "200px",
+      },
+    })
+    const style = wrapper
+      .find("[data-testid='chart-display']")
+      .attributes("style") ?? ""
+    expect(style).toContain("width: 640px")
+    expect(style).toContain("height: 200px")
+  })
+
+  it("accepts an array classList", () => {
+    const wrapper = mount(ChartDisplay, {
+      props: {
+        data: sampleData as ChartData,
+        classList: ["foo", "bar"],
+      },
+    })
+    const cls = wrapper
+      .find("[data-testid='chart-display']")
+      .attributes("class") ?? ""
+    expect(cls).toContain("foo")
+    expect(cls).toContain("bar")
+  })
+})

package/src/components/compositions/elements/display/ChartDisplay.vue

@@ -0,0 +1,152 @@
+<script setup lang="ts">
+/**
+ * Props-driven chart display.
+ *
+ * Renders any of Chart.js's standard chart types via `vue-chartjs`.
+ * Chart.js is "tree-shakable" — the components it needs (scales,
+ * elements, plugins) have to be registered once at module load before
+ * a chart can render. We do that side-effecting `Chart.register(...)`
+ * call at the top of this module so consumers don't have to think
+ * about it.
+ */
+import type { Component } from "vue"
+import type { ChartData, ChartOptions } from "chart.js"
+import { computed } from "vue"
+import {
+  ArcElement,
+  BarElement,
+  BubbleController,
+  CategoryScale,
+  Chart,
+  DoughnutController,
+  Filler,
+  Legend,
+  LinearScale,
+  LineController,
+  LineElement,
+  PieController,
+  PointElement,
+  PolarAreaController,
+  RadarController,
+  RadialLinearScale,
+  ScatterController,
+  Title,
+  Tooltip,
+  BarController,
+} from "chart.js"
+import {
+  Bar,
+  Bubble,
+  Doughnut,
+  Line,
+  Pie,
+  PolarArea,
+  Radar,
+  Scatter,
+} from "vue-chartjs"
+import { cn } from "@/lib/utils"
+
+// Register everything we expose. Idempotent — Chart.register is safe
+// to call multiple times.
+Chart.register(
+  CategoryScale,
+  LinearScale,
+  RadialLinearScale,
+  BarElement,
+  LineElement,
+  PointElement,
+  ArcElement,
+  BarController,
+  LineController,
+  PieController,
+  DoughnutController,
+  RadarController,
+  PolarAreaController,
+  BubbleController,
+  ScatterController,
+  Tooltip,
+  Legend,
+  Title,
+  Filler,
+)
+
+export type ChartDisplayType =
+  | "line"
+  | "bar"
+  | "pie"
+  | "doughnut"
+  | "radar"
+  | "polarArea"
+  | "bubble"
+  | "scatter"
+
+export interface ChartDisplayProps {
+  chartType?: ChartDisplayType
+  data: ChartData
+  options?: ChartOptions
+  width?: number | string
+  height?: number | string
+  classList?: string[] | string
+}
+
+const props = withDefaults(defineProps<ChartDisplayProps>(), {
+  chartType: "line",
+  width: "100%",
+  height: 300,
+})
+
+const componentMap: Record<ChartDisplayType, Component> = {
+  line: Line,
+  bar: Bar,
+  pie: Pie,
+  doughnut: Doughnut,
+  radar: Radar,
+  polarArea: PolarArea,
+  bubble: Bubble,
+  scatter: Scatter,
+}
+
+const chartComponent = computed<Component>(
+  () => componentMap[props.chartType] ?? Line,
+)
+
+const wrapperClass = computed<string>(() => {
+  const cl = props.classList
+  const base = "relative"
+  if (!cl) {
+    return base
+  }
+  const extra = Array.isArray(cl) ? cl.join(" ") : cl
+  return cn(base, extra)
+})
+
+const dimensionStyle = computed<Record<string, string>>(() => {
+  const toCss = (v: number | string): string =>
+    typeof v === "number" ? `${v}px` : v
+  return {
+    width: toCss(props.width),
+    height: toCss(props.height),
+  }
+})
+
+const mergedOptions = computed<ChartOptions>(() => ({
+  responsive: true,
+  maintainAspectRatio: false,
+  ...(props.options ?? {}),
+}))
+</script>
+
+<template>
+  <div
+    :class="wrapperClass"
+    :style="dimensionStyle"
+    data-testid="chart-display"
+    :data-chart-type="chartType"
+  >
+    <component
+      :is="chartComponent"
+      :data="data"
+      :options="mergedOptions"
+    />
+  </div>
+</template>

package/src/components/compositions/elements/display/HtmlDisplay.stories.ts

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from "@storybook/vue3"
+import HtmlDisplay from "./HtmlDisplay.vue"
+
+const meta = {
+  title: "Compositions/Elements/Display/HtmlDisplay",
+  component: HtmlDisplay,
+  tags: ["autodocs"],
+  args: {
+    value: "<p>This is <strong>raw HTML</strong>.</p>",
+  },
+  decorators: [
+    () => ({
+      template: '<div class="max-w-prose p-4"><story /></div>',
+    }),
+  ],
+} satisfies Meta<typeof HtmlDisplay>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { value: "<p>This is <strong>raw HTML</strong>.</p>" },
+}
+
+export const WithCustomContent: Story = {
+  args: {
+    value:
+      "<h2>Trusted content</h2><p>Pre-sanitised on the server, rendered as-is here.</p>",
+  },
+}
+
+export const Showcase: Story = {
+  args: {} as never,
+  render: () => ({
+    components: { HtmlDisplay },
+    template: `
+      <div class="flex flex-col gap-4">
+        <HtmlDisplay value="<p>First paragraph.</p>" />
+        <HtmlDisplay value="<ul><li>One</li><li>Two</li></ul>" />
+      </div>
+    `,
+  }),
+}

package/src/components/compositions/elements/display/HtmlDisplay.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest"
+import { mount } from "@vue/test-utils"
+import HtmlDisplay from "./HtmlDisplay.vue"
+
+describe("HtmlDisplay", () => {
+  it("renders raw HTML from value", () => {
+    const wrapper = mount(HtmlDisplay, { props: { value: "<p>Hello</p>" } })
+    expect(wrapper.find("p").exists()).toBe(true)
+    expect(wrapper.find("p").text()).toBe("Hello")
+  })
+
+  it("renders empty when value is null", () => {
+    const wrapper = mount(HtmlDisplay, { props: { value: null } })
+    expect(wrapper.html()).not.toContain("<p>")
+  })
+
+  it("renders nested elements as raw HTML", () => {
+    const wrapper = mount(HtmlDisplay, {
+      props: { value: "<span>from item</span>" },
+    })
+    expect(wrapper.find("span").exists()).toBe(true)
+    expect(wrapper.find("span").text()).toBe("from item")
+  })
+
+  it("applies classList (array) to the root", () => {
+    const wrapper = mount(HtmlDisplay, {
+      props: { value: "<p>x</p>", classList: ["custom"] },
+    })
+    expect(wrapper.attributes("class")).toContain("custom")
+  })
+
+  it("applies classList (string) to the root", () => {
+    const wrapper = mount(HtmlDisplay, {
+      props: { value: "<p>x</p>", classList: "extra" },
+    })
+    expect(wrapper.attributes("class")).toContain("extra")
+  })
+})