vlite3 1.4.16 → 1.4.17

package/components/SeoProvider/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Generic, framework-agnostic SEO contract.
+ *
+ * The goal of this layer is to keep SEO **normalization** (turning
+ * "store config + route context + page-specific overrides" into one
+ * canonical object) reusable, while letting the **application**
+ * (Nuxt, plain Vue + DOM, server-rendered HTML, …) decide **how** the
+ * data is actually emitted to the document head.
+ *
+ * The split is:
+ *
+ *   1. `SeoData`         — the final shape every consumer (Nuxt
+ *                          `useSeoMeta`, Open Graph crawler, plain
+ *                          `<meta>` injection) understands.
+ *   2. `SeoAdapter`      — a tiny interface the host app provides
+ *                          to apply `SeoData` to the document. In
+ *                          Nuxt this wraps `useSeoMeta` / `useHead`;
+ *                          in a Vue admin preview it mutates
+ *                          `document.head` directly. The provider
+ *                          itself never imports Nuxt or DOM APIs.
+ *   3. `useSeo`          — a Vue composable for components that
+ *                          want to declare per-page SEO context
+ *                          (page type, dynamic replacements, image).
+ *   4. `SeoProvider`     — the Vue component that owns the
+ *                          lifecycle: it merges the current page
+ *                          context, runs the normalizer, and calls
+ *                          the adapter on every change.
+ *
+ * Keeping the layer UI-agnostic means `vlite3` can ship SEO support
+ * without forcing every consumer onto Nuxt — and tests can run with
+ * a stub adapter that just records the last call.
+ */
+/**
+ * Final, fully-resolved SEO payload.
+ *
+ * Every field is **already normalized** — null vs empty string,
+ * fallbacks applied, dynamic tokens replaced. Consumers (Nuxt
+ * `useSeoMeta`, DOM mutation, SSR string templating) should be
+ * able to read this object and emit `<meta>` tags without further
+ * computation.
+ */
+export interface SeoData {
+    /** Page title, ready to feed `useSeoMeta({ title })` / `<title>`. */
+    title: string;
+    /**
+     * Optional title template, e.g. `"%s · Acme"`. Falsy → leave the
+     * host app's default behaviour in place.
+     */
+    titleTemplate?: string | null;
+    /** Meta description, 1–2 sentences, crawler-friendly. */
+    description: string;
+    /** Comma- or space-separated keywords. Empty string if unset. */
+    keywords: string;
+    /** Absolute canonical URL. Falsy → host decides (use `useRequestURL` etc.). */
+    canonicalUrl?: string | null;
+    /** Robots directive, e.g. `"index, follow"` or `"noindex, nofollow"`. */
+    robots?: string | null;
+    /** Absolute favicon URL (`.ico` / `.png`). */
+    favicon?: string | null;
+    /** Absolute share-image URL (used for both OG and Twitter by default). */
+    image?: string | null;
+    ogTitle?: string | null;
+    ogDescription?: string | null;
+    ogImage?: string | null;
+    ogImageAlt?: string | null;
+    ogUrl?: string | null;
+    ogType?: string | null;
+    ogSiteName?: string | null;
+    ogLocale?: string | null;
+    twitterCard?: string | null;
+    twitterTitle?: string | null;
+    twitterDescription?: string | null;
+    twitterImage?: string | null;
+    twitterSite?: string | null;
+    twitterCreator?: string | null;
+    /**
+     * Site name used in OG `site_name`. Today the `ogSiteName` field
+     * carries the same value — `siteName` is exposed separately for
+     * adapters that prefer to render it as JSON-LD instead of a meta
+     * tag.
+     */
+    siteName?: string | null;
+    /** Free-form JSON-LD block. Adapter decides whether to render. */
+    jsonLd?: Record<string, unknown> | null;
+}
+/**
+ * The full, normalized context the `SeoProvider` hands to its
+ * adapter. Same as `SeoData` plus the canonical `pageType` key
+ * (used for analytics / structured data) and the unresolved raw
+ * inputs in case the adapter needs them.
+ */
+export interface SeoPayload extends SeoData {
+    /**
+     * Logical page key, e.g. `"home"`, `"product"`, `"collection"`.
+     * Adapter can use it for breadcrumb JSON-LD, custom `<meta>`,
+     * or just logging.
+     */
+    pageType: string;
+}
+/**
+ * Partial SEO data a page (or any component) can push into the
+ * provider via `useSeo({ … })`. Anything not supplied is filled by
+ * the provider's defaults / store-level fallback. Keys with `null`
+ * explicitly clear the inherited value.
+ */
+export interface SeoContextInput {
+    pageType?: string;
+    title?: string | null;
+    description?: string | null;
+    keywords?: string | null;
+    image?: string | null;
+    canonicalUrl?: string | null;
+    robots?: string | null;
+    /**
+     * Token replacements applied to every string field, e.g.
+     * `{ productName: 'Blue Tee' }` for `{{productName}}`.
+     */
+    replacements?: Record<string, string | number | null | undefined>;
+    /**
+     * Free-form extras merged on top of the resolved payload. Use
+     * sparingly — the canonical fields above are preferred.
+     */
+    overrides?: Partial<SeoData>;
+}
+/**
+ * The contract a host application (Nuxt app, Vue admin shell,
+ * SSR template) provides so the generic `SeoProvider` can emit
+ * the resolved SEO without depending on any specific framework.
+ *
+ * The adapter receives the final, normalized payload. The
+ * provider calls it whenever the merged SEO context changes.
+ */
+export interface SeoAdapter {
+    /**
+     * Apply the SEO payload to the document. Called reactively on
+     * every change; may be called multiple times during a session
+     * (e.g. on route change, then on data load).
+     */
+    apply(payload: SeoPayload): void;
+    /**
+     * Optional cleanup hook, e.g. clearing injected meta tags when
+     * the provider unmounts. The default implementation in
+     * `normalizeSeo` no-ops.
+     */
+    reset?(): void;
+}

package/composables/useSeo.d.ts

@@ -0,0 +1,34 @@
+import { InjectionKey, Ref } from 'vue';
+import { SeoContextInput } from '../components/SeoProvider/types';
+/**
+ * Mutable, reactive bag of SEO contexts. The provider owns the
+ * ref; pages push into it. We keep it as a `Map` so multiple
+ * pages on the same route (e.g. a checkout step embedded in a
+ * parent) can each contribute, and so `clear()` removes only
+ * the calling page's contribution.
+ */
+export type SeoContextBag = Ref<Map<symbol, SeoContextInput>>;
+export declare const SEO_CONTEXT_KEY: InjectionKey<SeoContextBag>;
+/**
+ * Minimal interface the page-level composable needs from the
+ * provider. Exposed as a separate type so the provider component
+ * doesn't have to import Vue's `provide` / `inject` machinery
+ * from the composable side.
+ */
+export interface SeoContextRegistrar {
+    register(input: SeoContextInput): SeoContextHandle;
+}
+/**
+ * Per-page handle. `update()` replaces the registered context
+ * in place; `clear()` removes it.
+ */
+export interface SeoContextHandle {
+    update(next: SeoContextInput): void;
+    clear(): void;
+}
+/**
+ * Public composable. Safe to call outside a provider — falls
+ * back to a no-op registrar so admin shells and one-off tests
+ * don't have to wire the provider up just to render.
+ */
+export declare const useSeo: (input?: SeoContextInput) => SeoContextHandle;

package/composables/useSeo.js

@@ -0,0 +1,28 @@
+import { inject as r, onBeforeUnmount as u } from "vue";
+const a = /* @__PURE__ */ Symbol("vlite3:seo-context"), s = (o = {}) => {
+  const e = r(a, null);
+  if (!e)
+    return {
+      update: () => {
+      },
+      clear: () => {
+      }
+    };
+  const t = /* @__PURE__ */ Symbol("vlite3:seo-context-entry");
+  e.value.set(t, o);
+  const n = {
+    update(l) {
+      e.value.set(t, l);
+    },
+    clear() {
+      e.value.delete(t);
+    }
+  };
+  return u(() => {
+    e.value.delete(t);
+  }), n;
+};
+export {
+  a as SEO_CONTEXT_KEY,
+  s as useSeo
+};

package/index.d.ts

@@ -63,8 +63,10 @@ export * from './components/AsyncSelect';
 export * from './components/ImageComparison';
 export { default as ImageMagnifier } from './components/ImageMagnifier.vue';
 export * from './components/ThemeProvider';
+export * from './components/SeoProvider';
 export * from './components/ScaleGenerator';
 export { THEME_STYLES_KEY, useThemeStyles } from './composables/useThemeStyles';
+export { useSeo, SEO_CONTEXT_KEY, type SeoContextBag, type SeoContextHandle } from './composables/useSeo';
 export { default as Icon } from './components/Icon.vue';
 export { default as Logo } from './components/Logo.vue';
 export { default as Alert } from './components/Alert.vue';