nuxt-ui-tools 1.0.0 → 1.1.0

package/dist/runtime/dashboard/components/dashboard-refresh.vue

@@ -0,0 +1,86 @@
+<script setup>
+import UButton from "@nuxt/ui/components/Button.vue";
+import UDropdownMenu from "@nuxt/ui/components/DropdownMenu.vue";
+import UFieldGroup from "@nuxt/ui/components/FieldGroup.vue";
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import DashboardRelativeTime from "./dashboard-relative-time.vue";
+const {
+  dashboard,
+  intervals = [0, 30, 60, 300, 900],
+  updated = true,
+  label = true,
+  size = "sm"
+} = defineProps({
+  dashboard: { type: Object, required: true },
+  intervals: { type: Array, required: false },
+  updated: { type: Boolean, required: false },
+  label: { type: Boolean, required: false },
+  size: { type: String, required: false }
+});
+const { t, code } = useUiToolsLocale();
+const formatInterval = computed(() => {
+  const seconds = new Intl.NumberFormat(code.value, {
+    style: "unit",
+    unit: "second",
+    unitDisplay: "short"
+  });
+  const minutes = new Intl.NumberFormat(code.value, {
+    style: "unit",
+    unit: "minute",
+    unitDisplay: "short"
+  });
+  return (value) => value >= 60 && value % 60 === 0 ? minutes.format(value / 60) : seconds.format(value);
+});
+const items = computed(() => [
+  [{ label: t("dashboard.refresh.auto"), type: "label" }],
+  intervals.map((seconds) => ({
+    checked: dashboard.autoRefresh === seconds,
+    label: seconds > 0 ? formatInterval.value(seconds) : t("dashboard.refresh.off"),
+    onSelect: () => {
+      dashboard.autoRefresh = seconds;
+    },
+    type: "checkbox"
+  }))
+]);
+function refresh() {
+  dashboard.refresh().catch(() => void 0);
+}
+</script>
+
+<template>
+  <div class="flex items-center gap-3" data-dashboard-refresh>
+    <span
+      v-if="updated && dashboard.updatedAt !== void 0"
+      class="text-xs whitespace-nowrap text-muted max-sm:hidden"
+    >
+      {{ t("dashboard.freshness.prefix") }}
+      <DashboardRelativeTime :value="dashboard.updatedAt" />
+    </span>
+    <UFieldGroup :size>
+      <UButton
+        color="neutral"
+        variant="outline"
+        icon="i-lucide-refresh-cw"
+        :label="label ? t('dashboard.refresh.label') : void 0"
+        :aria-label="label ? void 0 : t('dashboard.refresh.label')"
+        :loading="dashboard.refreshing"
+        @click="refresh"
+      />
+      <UDropdownMenu :items :content="{ align: 'end', side: 'bottom', sideOffset: 6 }">
+        <UButton
+          color="neutral"
+          variant="outline"
+          trailing-icon="i-lucide-chevron-down"
+          :label="dashboard.autoRefresh > 0 ? formatInterval(dashboard.autoRefresh) : void 0"
+          :aria-label="t('dashboard.refresh.auto')"
+          :class="dashboard.autoRefresh > 0 && 'text-highlighted'"
+        >
+          <template v-if="dashboard.autoRefresh > 0" #leading>
+            <span aria-hidden="true" class="size-1.5 animate-pulse rounded-full bg-primary" />
+          </template>
+        </UButton>
+      </UDropdownMenu>
+    </UFieldGroup>
+  </div>
+</template>

package/dist/runtime/dashboard/components/dashboard-refresh.vue.d.ts

@@ -0,0 +1,29 @@
+/** What the control drives: the dashboard object returned by `useDashboard`. */
+interface DashboardRefreshTarget {
+    refresh: () => Promise<void>;
+    readonly refreshing: boolean;
+    readonly updatedAt: number | undefined;
+    autoRefresh: number;
+}
+/**
+ * Refresh control for a dashboard header: a refresh button, an auto-refresh interval menu (kept in
+ * the URL by the dashboard), and "Updated 3 min ago".
+ *
+ * @example
+ * ```vue
+ * <UiDashboardRefresh :dashboard />
+ * ```
+ */
+type __VLS_Props = {
+    dashboard: DashboardRefreshTarget;
+    /** Auto-refresh choices in seconds; `0` turns it off. */
+    intervals?: readonly number[];
+    /** Shows when the data on screen was last fetched. */
+    updated?: boolean;
+    /** Shows the "Refresh" label next to the icon. */
+    label?: boolean;
+    size?: 'xs' | 'sm' | 'md';
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/dashboard/components/dashboard-relative-time.d.vue.ts

@@ -0,0 +1,12 @@
+import type { DashboardTimeValue } from '../types/index.js';
+/**
+ * A time relative to now (`3 min ago`, `yesterday`), kept current by a shared 30-second clock, with
+ * the full date as a tooltip. Pairs with `dashboard.updatedAt` for a page-level freshness line.
+ */
+type __VLS_Props = {
+    /** A `Date`, epoch milliseconds, or an ISO string. Renders nothing while `null` / `undefined`. */
+    value: DashboardTimeValue | null | undefined;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/dashboard/components/dashboard-relative-time.vue

@@ -0,0 +1,23 @@
+<script setup>
+import { computed } from "vue";
+import { useDashboardTime } from "../composables/use-dashboard-time";
+import { toDashboardTime } from "../utils/time";
+const props = defineProps({
+  value: { type: null, required: true }
+});
+const time = useDashboardTime();
+const at = computed(
+  () => props.value === null || props.value === void 0 ? Number.NaN : toDashboardTime(props.value)
+);
+</script>
+
+<template>
+  <time
+    v-if="Number.isFinite(at)"
+    :datetime="new Date(at).toISOString()"
+    :title="time.absolute(at)"
+    data-allow-mismatch="text"
+  >
+    {{ time.relative(at) }}
+  </time>
+</template>

package/dist/runtime/dashboard/components/dashboard-relative-time.vue.d.ts

@@ -0,0 +1,12 @@
+import type { DashboardTimeValue } from '../types/index.js';
+/**
+ * A time relative to now (`3 min ago`, `yesterday`), kept current by a shared 30-second clock, with
+ * the full date as a tooltip. Pairs with `dashboard.updatedAt` for a page-level freshness line.
+ */
+type __VLS_Props = {
+    /** A `Date`, epoch milliseconds, or an ISO string. Renders nothing while `null` / `undefined`. */
+    value: DashboardTimeValue | null | undefined;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/dashboard/components/dashboard-stack-bar.d.vue.ts

@@ -0,0 +1,36 @@
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { DashboardBlockBaseProps, DashboardBlockUi, DashboardSelectEvent, DashboardSeriesColor, DashboardSourceLike, DashboardStackBarUi } from '../types/index.js';
+declare const __VLS_export: <TRow>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<Omit<DashboardBlockBaseProps, "ui"> & {
+        source: DashboardSourceLike<readonly TRow[] | undefined>;
+        label: (row: TRow) => LazyTextValue;
+        value: (row: TRow) => number;
+        /** Legend value text. Defaults to the share in percent. */
+        text?: (row: TRow, share: number) => LazyTextValue;
+        color?: (row: TRow, index: number) => DashboardSeriesColor | undefined;
+        /** Legend columns from the `sm` breakpoint (one column below). */
+        legendColumns?: 1 | 2;
+        /** Makes each segment and legend entry selectable. */
+        onSelect?: (event: DashboardSelectEvent<TRow>) => void;
+        ui?: DashboardBlockUi & DashboardStackBarUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        'header-right'?: () => unknown;
+        toolbar?: () => unknown;
+        footer?: () => unknown;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/dashboard/components/dashboard-stack-bar.vue

@@ -0,0 +1,162 @@
+<script setup>
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import { resolveTextValue } from "#ui-tools/shared/utils/render";
+import { useDashboardFormat } from "../composables/use-dashboard-format";
+import { useDashboardUi } from "../composables/use-dashboard-ui";
+import { resolveDashboardColor } from "../utils/charts";
+import { toDashboardCell } from "../utils/export";
+import {
+  DASHBOARD_ROW_BUTTON,
+  DASHBOARD_SELECTABLE_ROW,
+  resolveDashboardClasses
+} from "../utils/ui";
+import DashboardSkeleton from "./block/dashboard-skeleton.vue";
+import DashboardCard from "./dashboard-card.vue";
+const {
+  source,
+  card = true,
+  menu = void 0,
+  freshness = void 0,
+  label,
+  value,
+  text,
+  color,
+  legendColumns = 2,
+  onSelect,
+  ui,
+  ...block
+} = defineProps({
+  title: { type: [String, Number, Function], required: false },
+  subtitle: { type: [String, Number, Function], required: false },
+  size: { type: String, required: false },
+  rows: { type: String, required: false },
+  card: { type: Boolean, required: false },
+  activation: { type: String, required: false },
+  empty: { type: Object, required: false },
+  menu: { type: [Boolean, Array, Function], required: false },
+  actions: { type: Array, required: false },
+  freshness: { type: Boolean, required: false },
+  source: { type: Object, required: true },
+  label: { type: Function, required: true },
+  value: { type: Function, required: true },
+  text: { type: Function, required: false },
+  color: { type: Function, required: false },
+  legendColumns: { type: Number, required: false },
+  onSelect: { type: Function, required: false },
+  ui: { type: Object, required: false }
+});
+defineSlots();
+const { t } = useUiToolsLocale();
+const formats = useDashboardFormat();
+const appUi = useDashboardUi();
+const classes = computed(
+  () => resolveDashboardClasses(
+    {
+      item: "flex min-w-0 items-center gap-2",
+      legend: [
+        "grid grid-cols-1 gap-x-[18px] gap-y-2 text-[13px]",
+        legendColumns === 2 && "sm:grid-cols-2"
+      ].filter(Boolean).join(" "),
+      track: "mt-1.5 mb-4 flex h-3.5 gap-0.5 overflow-hidden rounded-full"
+    },
+    appUi.value.stackBar,
+    ui
+  )
+);
+const parts = computed(() => {
+  const data = source.data ?? [];
+  const values = data.map((row) => value(row));
+  const total = values.reduce((sum, amount) => sum + amount, 0);
+  return data.map((row, index) => {
+    const amount = values[index] ?? 0;
+    const share = total > 0 ? amount / total * 100 : 0;
+    return {
+      amount,
+      color: resolveDashboardColor(color?.(row, index), index),
+      index,
+      label: resolveTextValue(label(row)),
+      row,
+      share,
+      text: text ? resolveTextValue(text(row, share)) : formats.percent.value(share),
+      width: `${share}%`
+    };
+  });
+});
+function tabulate() {
+  return {
+    columns: [
+      { key: "label", label: t("dashboard.table.label"), numeric: false },
+      { key: "value", label: t("dashboard.table.value"), numeric: true },
+      { key: "share", label: t("dashboard.table.share"), numeric: true }
+    ],
+    rows: parts.value.map((part) => [
+      toDashboardCell(part.label),
+      toDashboardCell(part.amount, formats.number.value(part.amount)),
+      toDashboardCell(Math.round(part.share * 10) / 10, formats.percent.value(part.share))
+    ])
+  };
+}
+</script>
+
+<template>
+  <DashboardCard
+    v-bind="block"
+    :card
+    :menu
+    :freshness
+    :ui
+    :source
+    :is-empty="parts.length === 0"
+    :tabulate
+  >
+    <template #skeleton>
+      <DashboardSkeleton kind="stack" />
+    </template>
+    <template v-if="$slots['header-right']" #header-right>
+      <slot name="header-right" />
+    </template>
+    <template v-if="$slots.toolbar" #toolbar>
+      <slot name="toolbar" />
+    </template>
+    <template v-if="$slots.footer" #footer>
+      <slot name="footer" />
+    </template>
+
+    <div :class="classes.track">
+      <i
+        v-for="part in parts"
+        :key="part.index"
+        class="block h-full transition-[width] duration-500 ease-out"
+        :class="onSelect && 'cursor-pointer'"
+        :style="{ background: part.color, width: part.width }"
+        :title="`${part.label} \xB7 ${part.text}`"
+        @click="onSelect?.({ index: part.index, row: part.row })"
+      />
+    </div>
+    <ul :class="classes.legend">
+      <li
+        v-for="part in parts"
+        :key="part.index"
+        :class="[classes.item, onSelect && DASHBOARD_SELECTABLE_ROW]"
+      >
+        <span
+          aria-hidden="true"
+          class="size-[9px] shrink-0 rounded-[3px]"
+          :style="{ background: part.color }"
+        />
+        <span class="min-w-0 flex-1 truncate text-muted">{{ part.label }}</span>
+        <b class="shrink-0 font-semibold whitespace-nowrap text-highlighted tabular-nums">
+          {{ part.text }}
+        </b>
+        <button
+          v-if="onSelect"
+          type="button"
+          :class="DASHBOARD_ROW_BUTTON"
+          :aria-label="part.label"
+          @click="onSelect({ index: part.index, row: part.row })"
+        />
+      </li>
+    </ul>
+  </DashboardCard>
+</template>

package/dist/runtime/dashboard/components/dashboard-stack-bar.vue.d.ts

@@ -0,0 +1,36 @@
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { DashboardBlockBaseProps, DashboardBlockUi, DashboardSelectEvent, DashboardSeriesColor, DashboardSourceLike, DashboardStackBarUi } from '../types/index.js';
+declare const __VLS_export: <TRow>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<Omit<DashboardBlockBaseProps, "ui"> & {
+        source: DashboardSourceLike<readonly TRow[] | undefined>;
+        label: (row: TRow) => LazyTextValue;
+        value: (row: TRow) => number;
+        /** Legend value text. Defaults to the share in percent. */
+        text?: (row: TRow, share: number) => LazyTextValue;
+        color?: (row: TRow, index: number) => DashboardSeriesColor | undefined;
+        /** Legend columns from the `sm` breakpoint (one column below). */
+        legendColumns?: 1 | 2;
+        /** Makes each segment and legend entry selectable. */
+        onSelect?: (event: DashboardSelectEvent<TRow>) => void;
+        ui?: DashboardBlockUi & DashboardStackBarUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        'header-right'?: () => unknown;
+        toolbar?: () => unknown;
+        footer?: () => unknown;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/dashboard/components/dashboard-stat.d.vue.ts

@@ -0,0 +1,69 @@
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { DashboardBlockBaseProps, DashboardBlockUi, DashboardSeriesColor, DashboardSourceLike, DashboardStatUi, DashboardStatus, DashboardValueFormat } from '../types/index.js';
+declare const __VLS_export: <TData>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<Omit<DashboardBlockBaseProps, "ui" | "title" | "subtitle"> & {
+        source: DashboardSourceLike<TData>;
+        /** KPI label, shown above the value. */
+        label: LazyTextValue;
+        /** Main value. Numbers go through `format` (locale number format by default). */
+        value: (data: TData & ({} | null)) => LazyTextValue;
+        format?: DashboardValueFormat;
+        /**
+         * Change indicator, in percent by default. `null` hides it. Defaults to the change from
+         * `compare` when that is set.
+         */
+        delta?: (data: TData & ({} | null)) => number | null | undefined;
+        deltaFormat?: DashboardValueFormat;
+        /** A decrease is good news (e.g. a failure rate): colors the delta accordingly. */
+        invertDelta?: boolean;
+        /** Secondary text after the delta. Wraps under it when space runs out. */
+        caption?: string | ((data: TData & ({} | null)) => LazyTextValue | undefined);
+        icon?: string;
+        /** Recent values, oldest first, drawn as a sparkline under the value. `null` leaves a gap. */
+        trend?: (data: TData & ({} | null)) => readonly (number | null | undefined)[] | undefined;
+        /** How `trend` is drawn: a filled line (default), a bare line, or mini bars. */
+        trendType?: "area" | "line" | "bars";
+        trendColor?: DashboardSeriesColor;
+        /**
+         * The same measure over the comparison period (previous period, previous year). Gives the
+         * default `delta`, and the default caption ("vs 1,204 previous period").
+         */
+        compare?: (data: TData & ({} | null)) => number | null | undefined;
+        /**
+         * Caption shown with `compare`, as text or built from the formatted previous value. Defaults to
+         * "vs <value> previous period".
+         */
+        compareLabel?: LazyTextValue | ((previous: string) => LazyTextValue);
+        /**
+         * Target of a numeric `value`: draws a progress bar with the goal and the completion. `null`
+         * hides it.
+         */
+        goal?: (data: TData & ({} | null)) => number | null | undefined;
+        /** Status on the title row (a colored dot and label). `null` hides it. */
+        status?: (data: TData & ({} | null)) => DashboardStatus | null | undefined;
+        ui?: DashboardBlockUi & DashboardStatUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        value?: (props: {
+            data: TData & ({} | null);
+            value: string;
+        }) => unknown;
+        caption?: (props: {
+            data: TData & ({} | null);
+        }) => unknown;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};