@frigear-nu/ui 0.1.0 → 0.1.2

package/README.md

@@ -12,6 +12,7 @@ English fallbacks; every one of them can be overridden by a prop.
 | Component | Use |
 |---|---|
 | `PageHeading` | Title block of an app page: breadcrumb (array) or eyebrow line (string), `#badge`, description, meta row, `#actions` |
+| `PageSectionSwitcher` | Full-width button naming the current section, with a menu of all sections (mobile section navigation) |
 | `PageTabs` | Tabs under a heading: links (`to`, route decides) or state (`v-model` + `value`) |
 | `SectionCard` | A titled card for one section (form, key facts); `flush` for tables and lists |
 | `TableCard` | The surface a `UTable` sits in (`:ui="tableUi()"`), with `#header` and `#footer` (total, pagination) |

package/dist/runtime/components/global/PageSectionSwitcher.d.vue.ts

@@ -0,0 +1,14 @@
+import type { NavigationMenuItem } from '@nuxt/ui';
+/**
+ * A full-width button naming the current section, with a menu of all sections. The narrow-screen counterpart of a
+ * vertical section navigation (`UNavigationMenu`), which does not fit beside the content on a phone. Items are links
+ * (`to`), and the one with `active` is the current section; `PageTabs` stays for tabs a page owns.
+ */
+type __VLS_Props = {
+    items: NavigationMenuItem[];
+    /** Overrides the accessible name of the button. */
+    label?: string;
+};
+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/components/global/PageSectionSwitcher.vue

@@ -0,0 +1,41 @@
+<script setup>
+const props = defineProps({
+  items: { type: Array, required: true },
+  label: { type: String, required: false }
+});
+const t = useUiT("patterns");
+const current = computed(() => props.items.find((item) => item.active) ?? props.items[0]);
+const menu = computed(() => props.items.map((item) => ({
+  label: item.label,
+  icon: item.icon,
+  to: item.to,
+  target: item.target,
+  external: item.external,
+  active: item.active,
+  trailingIcon: item.active ? "i-lucide-check" : void 0
+})));
+const ariaLabel = computed(() => {
+  const name = props.label ?? t("sections", "Sections");
+  return current.value?.label ? `${name}: ${current.value.label}` : name;
+});
+</script>
+
+<template>
+  <UDropdownMenu
+    v-if="items.length"
+    :items="menu"
+    :content="{ align: 'start' }"
+    :ui="{ content: 'w-(--reka-dropdown-menu-trigger-width)' }"
+  >
+    <UButton
+      color="neutral"
+      variant="outline"
+      block
+      :icon="current?.icon"
+      trailing-icon="i-lucide-chevrons-up-down"
+      :label="current?.label"
+      :aria-label="ariaLabel"
+      :ui="{ trailingIcon: 'ms-auto text-dimmed' }"
+    />
+  </UDropdownMenu>
+</template>

package/dist/runtime/components/global/PageSectionSwitcher.vue.d.ts

@@ -0,0 +1,14 @@
+import type { NavigationMenuItem } from '@nuxt/ui';
+/**
+ * A full-width button naming the current section, with a menu of all sections. The narrow-screen counterpart of a
+ * vertical section navigation (`UNavigationMenu`), which does not fit beside the content on a phone. Items are links
+ * (`to`), and the one with `active` is the current section; `PageTabs` stays for tabs a page owns.
+ */
+type __VLS_Props = {
+    items: NavigationMenuItem[];
+    /** Overrides the accessible name of the button. */
+    label?: string;
+};
+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/composables/index.d.ts

@@ -1,4 +1,6 @@
 export * from './useAction.ts.js';
+export * from './useBootstrap.ts.js';
+export * from './useCachedFetch.ts.js';
 export * from './useConfirmDialog.ts.js';
 export * from './useCopyToClipboard.ts.js';
 export * from './useErrorToast.ts.js';

package/dist/runtime/composables/index.js

@@ -1,4 +1,6 @@
 export * from "./useAction.ts";
+export * from "./useBootstrap.ts";
+export * from "./useCachedFetch.ts";
 export * from "./useConfirmDialog.ts";
 export * from "./useCopyToClipboard.ts";
 export * from "./useErrorToast.ts";

package/dist/runtime/composables/useBootstrap.d.ts

@@ -0,0 +1,33 @@
+/** What the app knows about an area's last bootstrap: when it loaded and which keys it primed. */
+export interface BootstrapState {
+    at: number;
+    keys: string[];
+}
+export interface LoadBootstrapOptions {
+    /**
+     * How long (ms) a bootstrap counts as fresh: entering the area again within it makes no request. Keep it at or
+     * below the `ttl` of the composables it primes, so they always find their entry fresh. Default one minute.
+     */
+    ttl?: number;
+}
+export declare const BOOTSTRAP_TTL_MS: number;
+/** The last bootstrap of `scope` (`null` before the first, after `resetBootstrap` or when it failed). */
+export declare const useBootstrapState: (scope: string) => any;
+/**
+ * Load an area's user-scoped data in one request (`GET /api/_bootstrap?scope=<scope>`, served by `@frigear-nu/auth`)
+ * and prime the `useCachedFetch` entry of every key it returns, so the modules' composables (`useMyTickets()`,
+ * `useSubscription()`, ...) render without a request of their own. Call it from a route middleware of the area: it
+ * runs before the page's components set up, on the server and on every client navigation.
+ *
+ * - Server: the data goes into the payload, used by the server render and by hydration.
+ * - Hydration: the payload entries are remembered for later navigation; nothing is fetched.
+ * - Client navigation: fetches again only when the last bootstrap is older than `ttl`.
+ *
+ * Never throws: when the request fails (or leaves a key out) the composables fetch from their own endpoints.
+ */
+export declare function loadBootstrap(scope: string, options?: LoadBootstrapOptions): Promise<void>;
+/**
+ * Forget an area's bootstrap and the cache entries it primed, so the next visit loads them again. Call it when the
+ * data no longer belongs to the visitor (signing in or out).
+ */
+export declare function resetBootstrap(scope: string): void;

package/dist/runtime/composables/useBootstrap.js

@@ -0,0 +1,45 @@
+import { clearCachedFetch, primeCachedFetch } from "./useCachedFetch.js";
+export const BOOTSTRAP_TTL_MS = 60 * 1e3;
+const stateKey = (scope) => `ui:bootstrap:${scope}`;
+const inFlight = /* @__PURE__ */ new Map();
+export const useBootstrapState = (scope) => useState(stateKey(scope), () => null);
+export async function loadBootstrap(scope, options = {}) {
+  const nuxtApp = useNuxtApp();
+  const state = useBootstrapState(scope);
+  const ttl = options.ttl ?? BOOTSTRAP_TTL_MS;
+  if (import.meta.client) {
+    if (nuxtApp.isHydrating && nuxtApp.payload.serverRendered) {
+      if (!state.value) return;
+      for (const key of state.value.keys) {
+        const data = nuxtApp.payload.data[key];
+        if (data !== void 0) primeCachedFetch(key, data);
+      }
+      state.value = { ...state.value, at: Date.now() };
+      return;
+    }
+    if (state.value && Date.now() - state.value.at < ttl) return;
+    const pending = inFlight.get(scope);
+    if (pending) return pending;
+  }
+  const run = async () => {
+    try {
+      const fetcher = import.meta.server ? useRequestFetch() : $fetch;
+      const data = await fetcher("/api/_bootstrap", { query: { scope } });
+      nuxtApp.runWithContext(() => {
+        for (const [key, value] of Object.entries(data)) primeCachedFetch(key, value);
+      });
+      state.value = { at: Date.now(), keys: Object.keys(data) };
+    } catch (error) {
+      if (import.meta.dev) console.warn(`[ui] bootstrap "${scope}" failed, the pages load their own data:`, error);
+    }
+  };
+  if (import.meta.server) return run();
+  const promise = run().finally(() => inFlight.delete(scope));
+  inFlight.set(scope, promise);
+  return promise;
+}
+export function resetBootstrap(scope) {
+  const state = useBootstrapState(scope);
+  if (state.value?.keys.length) clearCachedFetch(state.value.keys);
+  state.value = null;
+}

package/dist/runtime/composables/useCachedFetch.d.ts

@@ -0,0 +1,76 @@
+import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import type { AsyncData, NuxtApp, NuxtError, UseFetchOptions } from 'nuxt/app';
+/** One remembered response: what `useFetch` produced (after `transform`) and when. */
+export interface CachedFetchEntry<T = unknown> {
+    at: number;
+    data: T;
+}
+export type CachedFetchStore = Record<string, CachedFetchEntry>;
+export type CachedFetchOptions<ResT, DataT = ResT> = Omit<UseFetchOptions<ResT, DataT>, 'key' | 'default' | 'getCachedData'> & {
+    /** The fetch key. Required: it names the cache entry, so composables that share data must share the key. */
+    key: MaybeRefOrGetter<string>;
+    /**
+     * How long (ms) a remembered response is reused when a component mounts again (client navigation) without asking
+     * the server. Leave it out to reuse it until `refresh()`; `0` always refetches. Either way the remembered response
+     * stays on screen while the new one loads.
+     */
+    ttl?: number;
+};
+export type CachedFetchResult<DataT> = Omit<Awaited<AsyncData<DataT | undefined, NuxtError | undefined>>, 'pending'> & {
+    /**
+     * `true` only while there is nothing to show yet: the first load of this key. Background refreshes (a stale cache,
+     * `refresh()`) keep the last data on screen and leave it `false`. Named `loading` so it does not shadow Nuxt's
+     * deprecated `pending` (which is `status === 'pending'`).
+     */
+    loading: ComputedRef<boolean>;
+};
+/** The shared, per-app cache behind `useCachedFetch`. Only the client writes to it, so it adds nothing to the payload. */
+export declare const useCachedFetchStore: () => Ref<CachedFetchStore>;
+/**
+ * Remember a response for `key` as if `useCachedFetch` had fetched it, e.g. data loaded ahead of time (a warm-up, an
+ * aggregated request such as `loadBootstrap`). `data` must have the shape the composable's `transform` produces.
+ *
+ * On the server it goes into this request's payload under `key`, where `useCachedFetch` finds it during server
+ * rendering (no request of its own) and the client finds it while hydrating. Prime before the components using
+ * `key` set up (a route middleware), so they see it.
+ */
+export declare function primeCachedFetch<T>(key: string, data: T): void;
+/**
+ * Forget remembered responses so the next mount fetches again: one key, the keys a predicate accepts, or all of them.
+ * Call it when the data no longer belongs to the visitor (signing out).
+ */
+export declare function clearCachedFetch(keys?: string | string[] | ((key: string) => boolean)): void;
+/**
+ * Where `useCachedFetch` gets data without a request, in this order:
+ * 1. while hydrating, the server's response from the payload (and it is remembered for later mounts); on the server,
+ *    data primed for this request (`primeCachedFetch`);
+ * 2. on a mount (`cause: 'initial'`), the remembered response while it is younger than `ttl`;
+ * 3. otherwise nothing, so `useFetch` fetches. Refreshes (`refresh()`, `refreshNuxtData`, watchers) always fetch.
+ *
+ * Exported for tests; use `useCachedFetch`.
+ */
+export declare function cachedFetchData(key: string, nuxtApp: Pick<NuxtApp, 'isHydrating' | 'payload'>, cause: string, cache: CachedFetchStore, ttl: number | undefined, now?: number, server?: boolean): {
+    data: unknown;
+    remember: boolean;
+} | undefined;
+/**
+ * `useFetch` whose data survives client navigation and that is awaitable in pages.
+ *
+ * Nuxt drops `useFetch` data once the last component using a key unmounts, so going back to a page blanked it and
+ * showed the empty state until a refetch landed. `useCachedFetch` remembers each response by `key` (see
+ * `cachedFetchData` for the order) and shows the remembered one at once, refetching in the background when it is
+ * older than `ttl`.
+ *
+ * - `data` is `undefined` until the first response; there is no `default`, so a failed request never looks like an
+ *   empty result. Check `error` (and `status`) and derive lists with `?? []`.
+ * - `loading` is `true` only while nothing is on screen yet: render a skeleton for it, never the empty state.
+ * - `await` it in pages so SSR renders with data; in a widget, use it without `await` and render from `loading`.
+ *
+ * ```ts
+ * const { data, error, loading, refresh } = await useCachedFetch<TicketDto[]>('/api/events/tickets/me', {
+ *   key: 'events:tickets:mine',
+ *   ttl: 60_000,
+ * })
+ * ```
+ */
+export declare function useCachedFetch<ResT, DataT = ResT>(request: string | Ref<string> | (() => string), options: CachedFetchOptions<ResT, DataT>): CachedFetchResult<DataT> & Promise<CachedFetchResult<DataT>>;

package/dist/runtime/composables/useCachedFetch.js

@@ -0,0 +1,61 @@
+const STATE_KEY = "ui:cached-fetch";
+export const useCachedFetchStore = () => useState(STATE_KEY, () => ({}));
+export function primeCachedFetch(key, data) {
+  if (import.meta.server) {
+    useNuxtApp().payload.data[key] = data;
+    return;
+  }
+  useCachedFetchStore().value[key] = markRaw({ at: Date.now(), data });
+}
+export function clearCachedFetch(keys) {
+  const cache = useCachedFetchStore();
+  const drops = keys === void 0 ? () => true : typeof keys === "function" ? keys : (key) => (Array.isArray(keys) ? keys : [keys]).includes(key);
+  cache.value = Object.fromEntries(Object.entries(cache.value).filter(([key]) => !drops(key)));
+}
+export function cachedFetchData(key, nuxtApp, cause, cache, ttl, now = Date.now(), server = !!import.meta.server) {
+  if ((nuxtApp.isHydrating || server && cause === "initial") && nuxtApp.payload.data[key] !== void 0) {
+    return { data: nuxtApp.payload.data[key], remember: true };
+  }
+  if (cause !== "initial") return void 0;
+  const entry = cache[key];
+  if (!entry) return void 0;
+  if (ttl !== void 0 && now - entry.at >= ttl) return void 0;
+  return { data: entry.data, remember: false };
+}
+export function useCachedFetch(request, options) {
+  const cache = useCachedFetchStore();
+  const { key, ttl, transform, ...rest } = options;
+  const remember = (name, data) => {
+    if (!import.meta.server) cache.value[name] = markRaw({ at: Date.now(), data });
+  };
+  const fetched = useFetch(request, {
+    ...rest,
+    key,
+    // No caller default: the remembered (possibly stale) response, so a refetch never blanks the screen, or nothing.
+    default: () => cache.value[toValue(key)]?.data,
+    getCachedData: (name, nuxtApp, ctx) => {
+      const hit = cachedFetchData(name, nuxtApp, ctx.cause, cache.value, ttl);
+      if (hit?.remember) remember(name, hit.data);
+      return hit?.data;
+    },
+    transform: async (input) => {
+      const output = transform ? await transform(input) : input;
+      remember(toValue(key), output);
+      return output;
+    }
+  });
+  const result = {
+    data: fetched.data,
+    status: fetched.status,
+    error: fetched.error,
+    refresh: fetched.refresh,
+    execute: fetched.execute,
+    clear: () => {
+      const name = toValue(key);
+      cache.value = Object.fromEntries(Object.entries(cache.value).filter(([entry]) => entry !== name));
+      fetched.clear();
+    },
+    loading: computed(() => fetched.status.value === "pending" && fetched.data.value === void 0)
+  };
+  return Object.assign(Promise.resolve(fetched).then(() => result), result);
+}

package/dist/runtime/i18n/lang/da.json

@@ -45,6 +45,7 @@
     "edit": "Redigér",
     "delete": "Slet",
     "confirm": "Bekræft",
+    "sections": "Sektioner",
     "breadcrumb": "Brødkrummesti",
     "sortBy": "Sortér efter {column}",
     "sortedAsc": "Sortér efter {column}, nu stigende",

package/dist/runtime/i18n/lang/en.json

@@ -45,6 +45,7 @@
     "edit": "Edit",
     "delete": "Delete",
     "confirm": "Confirm",
+    "sections": "Sections",
     "breadcrumb": "Breadcrumb",
     "sortBy": "Sort by {column}",
     "sortedAsc": "Sort by {column}, now ascending",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frigear-nu/ui",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared UI components and composables for Frigear Nuxt applications, built on Nuxt UI.",
   "license": "MIT",
   "homepage": "https://docs.frigear.dev/modules/ui",
@@ -34,17 +34,17 @@
     "dist"
   ],
   "dependencies": {
-    "@frigear-nu/module-kit": "1.1.0",
+    "@frigear-nu/module-kit": "1.1.2",
     "@nuxt/kit": "^4.6.1",
     "@vueuse/core": "^13.5.0",
     "defu": "^6.1.4"
   },
   "devDependencies": {
-    "@frigear-nu/eslint-config": "0.1.0",
+    "@frigear-nu/eslint-config": "0.1.2",
     "@nuxt/module-builder": "^1.0.3",
     "@nuxt/schema": "^4.6.1",
     "@nuxt/test-utils": "^4.3.2",
-    "@nuxt/ui": "^4.11.2",
+    "@nuxt/ui": "^4.12.0",
     "eslint": "^10.12.0",
     "monaco-editor": "^0.56.0",
     "nuxt": "^4.6.1",
@@ -55,7 +55,7 @@
     "vue-tsc": "^3.3.11"
   },
   "peerDependencies": {
-    "@nuxt/ui": "^4.11.2",
+    "@nuxt/ui": "^4.12.0",
     "nuxt": "^4.6.1",
     "vue": "3.x",
     "monaco-editor": "^0.56.0",