@omnitend/dashboard-for-laravel 0.10.0 → 0.13.1

package/resources/js/components/charts/DXLineChart.vue

@@ -0,0 +1,79 @@
+<!--
+  @component
+  A themed line chart. Thin wrapper around vue-chartjs (chart.js) with the
+  Bootstrap palette applied (themed stroke + translucent fill, smoothed line)
+  and dashboard-friendly defaults. Pass `labels` + `datasets`; `options`
+  deep-merges over the defaults.
+
+  Requires the optional peer deps `chart.js` and `vue-chartjs`.
+-->
+<template>
+  <div class="dx-chart">
+    <Line :data="chartData" :options="mergedOptions" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import { Line } from "vue-chartjs";
+import {
+  registerCharts,
+  baseOptions,
+  applyPalette,
+  mergeOptions,
+  type ChartValueFormat,
+} from "./chartTheme";
+
+registerCharts();
+
+interface Props {
+  /** X-axis category labels. */
+  labels: string[];
+  /** Chart.js datasets. Colours are themed when a dataset omits them. */
+  datasets: any[];
+  /** Chart.js options; deep-merged over the themed defaults. */
+  options?: Record<string, any>;
+  /** Format value-axis ticks and tooltips. */
+  valueFormat?: ChartValueFormat;
+  /** Currency symbol for valueFormat: "currency" (default "£"). */
+  currencySymbol?: string;
+  /** Locale for number formatting. */
+  locale?: string;
+  /** Show the legend (default: only when there is more than one dataset). */
+  showLegend?: boolean;
+}
+
+// `showLegend` defaults to `undefined` (not Vue's Boolean-cast `false`) so the
+// `?? datasets.length > 1` default can actually fire when it isn't passed.
+const props = withDefaults(defineProps<Props>(), {
+  currencySymbol: "£",
+  showLegend: undefined,
+});
+
+const chartData = computed(() => ({
+  labels: props.labels,
+  datasets: applyPalette(props.datasets, "line", props.labels.length),
+}));
+
+const mergedOptions = computed(() =>
+  mergeOptions(
+    baseOptions({
+      valueFormat: props.valueFormat,
+      currencySymbol: props.currencySymbol,
+      locale: props.locale,
+      showLegend: props.showLegend ?? props.datasets.length > 1,
+      hasValueAxis: true,
+    }),
+    props.options ?? {},
+  ),
+);
+</script>
+
+<style scoped>
+.dx-chart {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-height: 240px;
+}
+</style>

package/resources/js/components/charts/chartTheme.ts

@@ -0,0 +1,229 @@
+/**
+ * Shared theming for the DX*Chart wrappers: a categorical palette pulled from
+ * the live Bootstrap theme, dashboard-friendly default options (no gridlines /
+ * legend clutter, responsive, formatted ticks), and a one-time Chart.js
+ * registration. chart.js / vue-chartjs are OPTIONAL peer deps.
+ */
+import { Chart, registerables } from "chart.js";
+
+export type ChartValueFormat = "number" | "currency" | "percent";
+
+const isPlainObject = (value: unknown): value is Record<string, any> =>
+    !!value && typeof value === "object" && !Array.isArray(value);
+
+/** Deep-merge consumer `options` over the themed defaults (arrays replace). */
+export function mergeOptions(
+    base: Record<string, any>,
+    override: Record<string, any>,
+): Record<string, any> {
+    const result: Record<string, any> = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergeOptions(result[key], value);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+let registered = false;
+
+/**
+ * Register Chart.js (idempotent). Uses the full `registerables` set so every
+ * controller / scale / element / plugin (incl. Legend, Tooltip, Filler) is
+ * available — chart.js is an external peer dep, so this adds no bundle weight.
+ */
+export function registerCharts(): void {
+    if (registered) return;
+    Chart.register(...registerables);
+    registered = true;
+}
+
+// Bootstrap CSS variables to read, in a sensible categorical order. Fallbacks
+// mirror Bootstrap 5 defaults so charts still render without the theme (SSR /
+// tests / a consumer who didn't import the CSS).
+const PALETTE_VARS: Array<[string, string]> = [
+    ["--bs-primary", "#0d6efd"],
+    ["--bs-success", "#198754"],
+    ["--bs-info", "#0dcaf0"],
+    ["--bs-warning", "#ffc107"],
+    ["--bs-danger", "#dc3545"],
+    ["--bs-purple", "#6f42c1"],
+    ["--bs-teal", "#20c997"],
+    ["--bs-orange", "#fd7e14"],
+    ["--bs-pink", "#d63384"],
+    ["--bs-secondary", "#6c757d"],
+];
+
+/** Resolve the themed categorical palette from the document root. */
+export function getPalette(): string[] {
+    if (typeof document === "undefined" || typeof getComputedStyle === "undefined") {
+        return PALETTE_VARS.map(([, fallback]) => fallback);
+    }
+    const styles = getComputedStyle(document.documentElement);
+    return PALETTE_VARS.map(([name, fallback]) => {
+        const value = styles.getPropertyValue(name).trim();
+        return value || fallback;
+    });
+}
+
+/** Read a single theme colour (e.g. the body text colour) with a fallback. */
+function themeColor(name: string, fallback: string): string {
+    if (typeof document === "undefined" || typeof getComputedStyle === "undefined") {
+        return fallback;
+    }
+    const value = getComputedStyle(document.documentElement)
+        .getPropertyValue(name)
+        .trim();
+    return value || fallback;
+}
+
+/** Add an alpha channel to a hex or rgb() colour (best-effort). */
+export function withAlpha(color: string, alpha: number): string {
+    const hex = color.replace(/^#/, "");
+    if (/^[0-9a-f]{6}$/i.test(hex)) {
+        const r = parseInt(hex.slice(0, 2), 16);
+        const g = parseInt(hex.slice(2, 4), 16);
+        const b = parseInt(hex.slice(4, 6), 16);
+        return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+    const rgbMatch = color.match(/^rgba?\(([^)]+)\)$/);
+    if (rgbMatch) {
+        const [r, g, b] = rgbMatch[1].split(",").map((n) => n.trim());
+        return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+    return color;
+}
+
+/** Format a numeric value per the chart's value format (for tick/tooltips). */
+export function formatValue(
+    value: number,
+    format: ChartValueFormat | undefined,
+    currencySymbol: string,
+    locale?: string,
+): string {
+    const num = new Intl.NumberFormat(locale, {
+        maximumFractionDigits: 2,
+    }).format(value);
+    if (format === "currency") return `${currencySymbol}${num}`;
+    if (format === "percent") return `${num}%`;
+    return num;
+}
+
+export interface BaseOptionArgs {
+    valueFormat?: ChartValueFormat;
+    currencySymbol?: string;
+    locale?: string;
+    /** Show the legend (default: false for a single dataset, true for many). */
+    showLegend?: boolean;
+    /** Whether the chart has value axes (bar/line) vs none (doughnut). */
+    hasValueAxis?: boolean;
+}
+
+/** Dashboard default Chart.js options merged under any consumer `options`. */
+export function baseOptions(args: BaseOptionArgs): Record<string, any> {
+    const {
+        valueFormat,
+        currencySymbol = "£",
+        locale,
+        showLegend = false,
+        hasValueAxis = true,
+    } = args;
+
+    const gridColor = withAlpha(themeColor("--bs-border-color", "#dee2e6"), 0.6);
+    const tickColor = themeColor("--bs-secondary-color", "#6c757d");
+
+    const options: Record<string, any> = {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: {
+            legend: { display: showLegend, labels: { color: tickColor } },
+            tooltip: {
+                callbacks: {
+                    label: (ctx: any) => {
+                        const raw = ctx.parsed?.y ?? ctx.parsed ?? ctx.raw;
+                        const value = typeof raw === "number" ? raw : Number(raw);
+                        const formatted = Number.isFinite(value)
+                            ? formatValue(value, valueFormat, currencySymbol, locale)
+                            : String(raw);
+                        const label = ctx.dataset?.label ?? ctx.label ?? "";
+                        return label ? `${label}: ${formatted}` : formatted;
+                    },
+                },
+            },
+        },
+    };
+
+    if (hasValueAxis) {
+        options.scales = {
+            x: {
+                grid: { display: false },
+                border: { color: gridColor },
+                ticks: { color: tickColor },
+            },
+            y: {
+                beginAtZero: true,
+                grid: { color: gridColor, drawBorder: false },
+                border: { display: false },
+                ticks: {
+                    color: tickColor,
+                    callback: (value: number | string) =>
+                        formatValue(Number(value), valueFormat, currencySymbol, locale),
+                },
+            },
+        };
+    }
+
+    return options;
+}
+
+/**
+ * Apply the themed palette to any dataset that doesn't set its own colours.
+ * Bar: one colour per dataset (or per bar for a single dataset). Line: a themed
+ * stroke + translucent fill. Doughnut/pie: one colour per slice.
+ */
+export function applyPalette(
+    datasets: any[],
+    kind: "bar" | "line" | "doughnut",
+    labelsCount: number,
+): any[] {
+    const palette = getPalette();
+    const single = datasets.length === 1;
+
+    return datasets.map((dataset, index) => {
+        const next = { ...dataset };
+        const color = palette[index % palette.length];
+
+        if (kind === "doughnut") {
+            if (next.backgroundColor === undefined) {
+                next.backgroundColor = Array.from(
+                    { length: labelsCount },
+                    (_, i) => palette[i % palette.length],
+                );
+            }
+            return next;
+        }
+
+        if (kind === "line") {
+            if (next.borderColor === undefined) next.borderColor = color;
+            if (next.backgroundColor === undefined) {
+                next.backgroundColor = withAlpha(color, 0.15);
+            }
+            if (next.tension === undefined) next.tension = 0.3;
+            if (next.fill === undefined) next.fill = true;
+            if (next.pointRadius === undefined) next.pointRadius = 2;
+            return next;
+        }
+
+        // bar
+        if (next.backgroundColor === undefined) {
+            next.backgroundColor =
+                single && labelsCount > 1
+                    ? Array.from({ length: labelsCount }, () => color)
+                    : color;
+        }
+        if (next.borderRadius === undefined) next.borderRadius = 4;
+        return next;
+    });
+}

package/resources/js/components/extended/DXDashboard.vue

@@ -52,10 +52,15 @@
 
       <!-- Page Content -->
       <main class="dashboard-main p-4">
-        <DContainer fluid>
+        <!-- Fluid: full-width, left-aligned content (for wide tables / admin
+             pages). Default: a centred reading-width column. -->
+        <DContainer v-if="fluid" fluid :class="contentClass">
+          <!-- @slot Default slot for the main page content. Full-width when `fluid`, otherwise a centred reading-width column. -->
+          <slot />
+        </DContainer>
+        <DContainer v-else fluid>
           <DRow class="justify-content-center">
-            <DCol cols="12" xl="10">
-              <!-- @slot Default slot for the main page content, rendered in the centred content column. -->
+            <DCol cols="12" xl="10" :class="contentClass">
               <slot />
             </DCol>
           </DRow>
@@ -89,6 +94,16 @@ interface Props {
   /** Page title shown in navbar */
   pageTitle?: string;
 
+  /**
+   * Render the page content full-width and left-aligned instead of the default
+   * centred, reading-width (`col-xl-10`) column. Use for data-heavy admin pages
+   * (wide tables).
+   */
+  fluid?: boolean;
+
+  /** Extra class(es) applied to the content container/column. */
+  contentClass?: string;
+
   /** User object for navbar dropdown */
   user?: { name: string; email: string } | null;
 

package/resources/js/components/extended/DXStatCard.vue

@@ -0,0 +1,211 @@
+<!--
+  @component
+  A KPI / stat tile: a big formatted value with a title, optional subtitle, an
+  optional up/down delta badge (auto-coloured + arrowed) versus a comparison,
+  and an optional trend/sparkline slot. Themed with Bootstrap variables.
+-->
+<template>
+  <DCard class="dx-stat-card" body-class="dx-stat-card__body">
+    <div class="dx-stat-card__head">
+      <div class="dx-stat-card__heading">
+        <div class="dx-stat-card__title">{{ title }}</div>
+        <div v-if="subtitle" class="dx-stat-card__subtitle">{{ subtitle }}</div>
+      </div>
+      <div v-if="$slots.icon" class="dx-stat-card__icon">
+        <!-- @slot Optional icon/visual in the top-right of the card. -->
+        <slot name="icon" />
+      </div>
+    </div>
+
+    <div class="dx-stat-card__value">
+      <!--
+        @slot Override the rendered value.
+        @binding {string} formatted The value formatted per `format`.
+        @binding {string | number} value The raw value prop.
+      -->
+      <slot name="value" :formatted="formattedValue" :value="value">
+        {{ formattedValue }}
+      </slot>
+    </div>
+
+    <div v-if="hasDelta || deltaLabel || $slots.trend" class="dx-stat-card__foot">
+      <DBadge
+        v-if="hasDelta"
+        :variant="deltaVariant"
+        class="dx-stat-card__delta"
+      >
+        <span class="dx-stat-card__delta-arrow" aria-hidden="true">{{ deltaArrow }}</span>
+        {{ formattedDelta }}
+      </DBadge>
+      <span v-if="deltaLabel" class="dx-stat-card__delta-label text-muted">
+        {{ deltaLabel }}
+      </span>
+      <div v-if="$slots.trend" class="dx-stat-card__trend">
+        <!-- @slot Trend visual (e.g. a sparkline) shown in the card footer. -->
+        <slot name="trend" />
+      </div>
+    </div>
+  </DCard>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import DCard from "../base/DCard.vue";
+import DBadge from "../base/DBadge.vue";
+
+type StatFormat = "number" | "currency" | "percent";
+type DeltaDirection = "up" | "down" | "neutral";
+
+interface Props {
+  /** Metric label, e.g. "Revenue". */
+  title: string;
+  /** Optional secondary line under the title, e.g. "This week". */
+  subtitle?: string;
+  /** The metric value. Numbers are formatted per `format`; strings pass through. */
+  value: string | number;
+  /** How to format a numeric `value` (default: plain number with grouping). */
+  format?: StatFormat;
+  /** Currency symbol for `format: "currency"` (default "£"). */
+  currencySymbol?: string;
+  /** Decimal places (default: 2 for currency, 0 otherwise). */
+  precision?: number;
+  /** Locale for number grouping/formatting (default: the runtime's). */
+  locale?: string;
+
+  /** Change versus a comparison period. Its sign drives the arrow/colour. */
+  delta?: number;
+  /** How to format the delta (default "percent"). */
+  deltaFormat?: StatFormat;
+  /** Force the delta direction instead of deriving it from `delta`'s sign. */
+  deltaDirection?: DeltaDirection;
+  /** Caption beside the delta, e.g. "vs last week". */
+  deltaLabel?: string;
+  /**
+   * Invert the delta colour: by default an up delta is positive (success/green)
+   * and a down delta negative (danger/red). Set for metrics where down is good
+   * (costs, bounce rate, …).
+   */
+  invertDelta?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  format: "number",
+  currencySymbol: "£",
+  deltaFormat: "percent",
+  invertDelta: false,
+});
+
+function formatNumber(value: number, fmt: StatFormat): string {
+  const fractionDigits =
+    props.precision ?? (fmt === "currency" ? 2 : 0);
+  const formatted = new Intl.NumberFormat(props.locale, {
+    minimumFractionDigits: fractionDigits,
+    maximumFractionDigits: fractionDigits,
+  }).format(value);
+
+  if (fmt === "currency") return `${props.currencySymbol}${formatted}`;
+  if (fmt === "percent") return `${formatted}%`;
+  return formatted;
+}
+
+const formattedValue = computed<string>(() => {
+  const raw = props.value;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return String(raw);
+  return formatNumber(raw, props.format);
+});
+
+const hasDelta = computed(
+  () => typeof props.delta === "number" && Number.isFinite(props.delta),
+);
+
+const deltaDirection = computed<DeltaDirection>(() => {
+  if (props.deltaDirection) return props.deltaDirection;
+  if (!hasDelta.value || props.delta === 0) return "neutral";
+  return (props.delta as number) > 0 ? "up" : "down";
+});
+
+const deltaArrow = computed(() => {
+  if (deltaDirection.value === "up") return "▲";
+  if (deltaDirection.value === "down") return "▼";
+  return "→";
+});
+
+const deltaVariant = computed<string>(() => {
+  if (deltaDirection.value === "neutral") return "secondary";
+  const isPositive = deltaDirection.value === "up";
+  const good = props.invertDelta ? !isPositive : isPositive;
+  return good ? "success" : "danger";
+});
+
+// Show the magnitude; the arrow conveys direction.
+const formattedDelta = computed<string>(() => {
+  if (!hasDelta.value) return "";
+  return formatNumber(Math.abs(props.delta as number), props.deltaFormat);
+});
+</script>
+
+<style scoped>
+.dx-stat-card :deep(.dx-stat-card__body) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.dx-stat-card__head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.dx-stat-card__title {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--bs-secondary-color);
+}
+
+.dx-stat-card__subtitle {
+  font-size: 0.8125rem;
+  color: var(--bs-secondary-color);
+}
+
+.dx-stat-card__icon {
+  color: var(--bs-secondary-color);
+  flex-shrink: 0;
+}
+
+.dx-stat-card__value {
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.1;
+  color: var(--bs-emphasis-color, var(--bs-body-color));
+}
+
+.dx-stat-card__foot {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.dx-stat-card__delta {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.2rem;
+}
+
+.dx-stat-card__delta-arrow {
+  font-size: 0.7em;
+  line-height: 1;
+}
+
+.dx-stat-card__delta-label {
+  font-size: 0.8125rem;
+}
+
+.dx-stat-card__trend {
+  margin-left: auto;
+}
+</style>