vlite3 1.4.15 → 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/components/ThemeProvider/ThemeProvider.vue.js

@@ -1,8 +1,8 @@
-import { defineComponent as m, useId as c, computed as o, provide as v, openBlock as i, createElementBlock as f, normalizeStyle as p, normalizeClass as C, createBlock as h, resolveDynamicComponent as y, withCtx as S, createTextVNode as b, toDisplayString as g, renderSlot as T } from "vue";
-import { buildThemeVariables as k, buildThemeStyleBlock as B, buildCardOverrideStyles as _ } from "./themeVars.js";
-import { THEME_STYLES_KEY as E } from "../../composables/useThemeStyles.js";
-import { isDarkColor as x } from "../../utils/colorUtils.js";
-const V = /* @__PURE__ */ m({
+import { defineComponent as m, computed as o, provide as u, openBlock as a, createElementBlock as v, normalizeClass as c, createBlock as f, resolveDynamicComponent as p, withCtx as h, createTextVNode as C, toDisplayString as b, renderSlot as g } from "vue";
+import { buildThemeVariables as S, buildThemeStyleBlock as y, buildCardOverrideStyles as T } from "./themeVars.js";
+import { THEME_STYLES_KEY as k } from "../../composables/useThemeStyles.js";
+import { isDarkColor as B } from "../../utils/colorUtils.js";
+const P = /* @__PURE__ */ m({
   __name: "ThemeProvider",
   props: {
     bgColor: { default: void 0 },
@@ -14,35 +14,33 @@ const V = /* @__PURE__ */ m({
     maxWidth: { default: void 0 },
     rootClass: { default: void 0 }
   },
-  setup(r) {
-    const e = r, t = `vlite-theme-provider-${c()}`, a = o(() => e.bgColor ? x(e.bgColor) : !1), l = o(() => k(e)), d = o(
-      () => B(l.value, t)
+  setup(t) {
+    const e = t, r = o(() => e.bgColor ? B(e.bgColor) : !1), l = o(() => S(e)), i = o(
+      () => y(l.value, ".vlite-theme-provider")
+    ), d = o(
+      () => e.bgColor ? T(e.bgColor, r.value, ".vlite-theme-provider") : ""
     ), s = o(
-      () => e.bgColor ? _(e.bgColor, a.value, `#${t}`) : ""
-    ), n = o(
-      () => [d.value, s.value].filter(Boolean).join(`
+      () => [i.value, d.value].filter(Boolean).join(`
 `)
     );
-    return v(E, l), (u, D) => (i(), f("div", {
-      id: t,
-      class: C([
+    return u(k, l), (n, _) => (a(), v("div", {
+      class: c([
         "vlite-theme-provider",
-        r.rootClass,
+        t.rootClass,
         "transition-colors duration-300",
-        { dark: a.value }
-      ]),
-      style: p(l.value)
+        { dark: r.value }
+      ])
     }, [
-      (i(), h(y("style"), null, {
-        default: S(() => [
-          b(g(n.value), 1)
+      (a(), f(p("style"), null, {
+        default: h(() => [
+          C(b(s.value), 1)
         ]),
         _: 1
       })),
-      T(u.$slots, "default")
-    ], 6));
+      g(n.$slots, "default")
+    ], 2));
   }
 });
 export {
-  V as default
+  P as default
 };

package/components/ThemeProvider/themeVars.d.ts

@@ -11,7 +11,7 @@ export declare const DEFAULT_MAX_WIDTH = 1440;
 export declare function buildCardOverrideStyles(bg: string, isDark: boolean, scope?: string): string;
 /**
  * Build a `<style>` text block that re-applies every generated CSS custom
- * property with `!important`, scoped to a unique `#id` selector.
+ * property with `!important`, scoped to a provider root selector.
  *
  * Why this exists:
  *
@@ -25,11 +25,9 @@ export declare function buildCardOverrideStyles(bg: string, isDark: boolean, sco
  *   `[data-theme="dark"]` block. That silently nukes the provider's
  *   inline values and the brand color disappears.
  *
- *   The fix is a redundant layer that has the *highest* priority
- *   CSS offers: an ID selector combined with `!important`. With
- *   `#<id> { --var: v !important; }` nothing else in the cascade
- *   can override the theme — not Tailwind defaults, not ERP global
- *   styles, not third-party stylesheets.
+ *   The fix is a redundant layer that has the same behavior as
+ *   `ShopThemeProvider`: a generated style rule that writes every
+ *   theme token with `!important` on the provider root.
  *
  * Pure: no DOM, no Vue. Returns a CSS string ready to be dropped
  * inside a `<component :is="'style'">{{ block }}</component>` block.
@@ -38,20 +36,18 @@ export declare function buildCardOverrideStyles(bg: string, isDark: boolean, sco
  * provider root `font-size` that drives the same inherited base-size behavior
  * as `ShopThemeProvider`.
  */
-export declare function buildThemeStyleBlock(vars: ThemeStyles, id: string): string;
+export declare function buildThemeStyleBlock(vars: ThemeStyles, selector?: string): string;
 /**
- * Note: We previously tried to stamp `!important` directly onto every value
- * in the theme variables object, so that Vue inline bindings (`:style="themeStyles"`)
- * would carry the `!important` flag.
+ * Note: We keep `!important` out of the theme variables object itself.
  *
  * However, Vue's DOM patching (`style.setProperty(key, value)`) strictly rejects
  * the `value` argument if it contains `!important`. Thus, any inline style
  * object with `!important` silently fails and drops the styles entirely in SPA
  * environments.
  *
- * Therefore, we provide the raw variables (without `!important`) to `useThemeStyles()`
- * consumers, and rely exclusively on the `<style>` block generated by
- * `buildThemeStyleBlock` to enforce `!important` overrides across the application.
+ * Therefore, we provide raw variables (without `!important`) to `useThemeStyles()`
+ * consumers, and rely on the `<style>` block generated by `buildThemeStyleBlock`
+ * to enforce `!important` overrides across the application.
  */
 /**
  * Compute the full theme-styles record from a {@link ThemeProviderProps}.

package/components/ThemeProvider/themeVars.js

@@ -345,7 +345,7 @@ ${l} .bg-card-light .bg-card-light .bg-card-light {
 `;
 }
 const O = (r) => r.replace(/[{};]/g, "");
-function U(r, o) {
+function U(r, o = ".vlite-theme-provider") {
   if (!o) return "";
   const l = [];
   for (const [e, f] of Object.entries(r)) {
@@ -355,7 +355,7 @@ function U(r, o) {
       c.includes("!important") ? `  ${e}: ${c};` : `  ${e}: ${c} !important;`
     );
   }
-  return l.length === 0 ? "" : `#${o} {
+  return l.length === 0 ? "" : `${o} {
 ${l.join(`
 `)}
 }

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';