@brumaombra/ui-vintage 0.8.0 → 0.8.1

package/COMPONENTS.md

@@ -20,7 +20,7 @@ This file lists every public entry point of the package with its components, pro
 - **Data display:** [animated-number](#brumaombraui-vintageanimated-number), [avatar](#brumaombraui-vintageavatar), [badge](#brumaombraui-vintagebadge), [card](#brumaombraui-vintagecard), [card-grid](#brumaombraui-vintagecard-grid), [chip](#brumaombraui-vintagechip), [data-list](#brumaombraui-vintagedata-list), [data-table](#brumaombraui-vintagedata-table), [info-card](#brumaombraui-vintageinfo-card), [progress](#brumaombraui-vintageprogress), [progress-component](#brumaombraui-vintageprogress-component), [scroll-area](#brumaombraui-vintagescroll-area), [separator](#brumaombraui-vintageseparator), [single-value-card](#brumaombraui-vintagesingle-value-card), [skeleton](#brumaombraui-vintageskeleton), [table](#brumaombraui-vintagetable)
 - **Navigation:** [accordion](#brumaombraui-vintageaccordion), [breadcrumb](#brumaombraui-vintagebreadcrumb), [collapsible](#brumaombraui-vintagecollapsible), [pagination](#brumaombraui-vintagepagination), [sidebar](#brumaombraui-vintagesidebar), [stepper](#brumaombraui-vintagestepper), [tabs](#brumaombraui-vintagetabs)
 - **Overlays:** [alert-dialog](#brumaombraui-vintagealert-dialog), [command](#brumaombraui-vintagecommand), [dialog](#brumaombraui-vintagedialog), [hover-card](#brumaombraui-vintagehover-card), [popover](#brumaombraui-vintagepopover), [sheet](#brumaombraui-vintagesheet), [tooltip](#brumaombraui-vintagetooltip)
-- **Feedback:** [alert](#brumaombraui-vintagealert), [busy](#brumaombraui-vintagebusy), [busy-indicator](#brumaombraui-vintagebusy-indicator), [confirm-dialog](#brumaombraui-vintageconfirm-dialog), [empty-state-card](#brumaombraui-vintageempty-state-card), [loading-state-card](#brumaombraui-vintageloading-state-card), [message-dialog](#brumaombraui-vintagemessage-dialog), [message-toast](#brumaombraui-vintagemessage-toast), [spinner](#brumaombraui-vintagespinner)
+- **Feedback:** [alert](#brumaombraui-vintagealert), [busy](#brumaombraui-vintagebusy), [busy-indicator](#brumaombraui-vintagebusy-indicator), [confirm-dialog](#brumaombraui-vintageconfirm-dialog), [cookie-consent](#brumaombraui-vintagecookie-consent), [empty-state-card](#brumaombraui-vintageempty-state-card), [loading-state-card](#brumaombraui-vintageloading-state-card), [message-dialog](#brumaombraui-vintagemessage-dialog), [message-toast](#brumaombraui-vintagemessage-toast), [spinner](#brumaombraui-vintagespinner)
 - **Layouts and app shell:** [background-grid](#brumaombraui-vintagebackground-grid), [dashboard-shell](#brumaombraui-vintagedashboard-shell), [error-page](#brumaombraui-vintageerror-page), [landing](#brumaombraui-vintagelanding), [landing-content](#brumaombraui-vintagelanding-content), [landing-footer](#brumaombraui-vintagelanding-footer), [landing-navbar](#brumaombraui-vintagelanding-navbar), [landing-shell](#brumaombraui-vintagelanding-shell), [language-flag](#brumaombraui-vintagelanguage-flag), [language-selector](#brumaombraui-vintagelanguage-selector), [page-header](#brumaombraui-vintagepage-header), [theme-selector](#brumaombraui-vintagetheme-selector)
 - **Content and blog:** [blog](#brumaombraui-vintageblog), [content](#brumaombraui-vintagecontent)
 - **Utilities and types:** [common-types](#brumaombraui-vintagecommon-types), [utils](#brumaombraui-vintageutils)
@@ -2814,6 +2814,47 @@ interface ShowConfirmDialogOptions {
 
 ---
 
+### `@brumaombra/ui-vintage/cookie-consent`
+
+Cookie consent banner fixed to the bottom of the page, shown in the browser until the visitor accepts or declines. The choice is saved in `localStorage` under `storage-key`; `useCookieConsent(storageKey)` shares it, so optional scripts (analytics, ads) can wait for `consent.value === "granted"` and a settings page can call `reset()` to ask again. Texts have translated defaults, `policy-to` adds a link to the cookie policy.
+
+```ts
+import { CookieConsent, useCookieConsent } from '@brumaombra/ui-vintage/cookie-consent';
+import type { CookieConsentValue } from '@brumaombra/ui-vintage/cookie-consent';
+```
+
+```vue
+<CookieConsent storage-key="analyticsConsent" policy-to="/cookie-policy" @accept="loadAnalytics" />
+
+<script setup>
+const { consent, reset } = useCookieConsent('analyticsConsent');
+watch(consent, value => value === 'granted' && loadAnalytics(), { immediate: true });
+</script>
+```
+
+#### `CookieConsent`
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `storageKey` | `string` | `'cookieConsent'` |
+| `message` | `string` | `undefined` |
+| `policyTo` | `string` | `undefined` |
+| `policyLabel` | `string` | `undefined` |
+| `acceptLabel` | `string` | `undefined` |
+| `declineLabel` | `string` | `undefined` |
+| `class` | `HTMLAttributes['class']` | `undefined` |
+
+- **Emits:** `accept`, `decline`.
+
+#### Functions, constants, and types
+
+```ts
+function useCookieConsent(storageKey = 'cookieConsent')
+type CookieConsentValue = 'granted' | 'denied' | null
+```
+
+---
+
 ### `@brumaombra/ui-vintage/empty-state-card`
 
 Empty state with an icon, title, description, and an `action` slot. Falls back to localized default copy.

package/README.md

@@ -358,7 +358,7 @@ There is no required library build step before publishing. The normal verificati
 npm run typecheck
 ```
 
-For release details, see [NPM.md](NPM.md). The package is published under the public npm scope `@brumaombra/ui-vintage`.
+For the release process, see the project skill in [`.claude/skills/publish-npm/SKILL.md`](.claude/skills/publish-npm/SKILL.md). The package is published under the public npm scope `@brumaombra/ui-vintage`.
 
 <a id="requirements"></a>
 ## 🧰 Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@brumaombra/ui-vintage",
-    "version": "0.8.0",
+    "version": "0.8.1",
     "description": "Source-published Nuxt UI runtime with shared theme tokens and built-in Nuxt integrations.",
     "private": false,
     "author": "Mauro Brambilla",
@@ -59,6 +59,7 @@
         "./command": "./src/components/ui/command/index.ts",
         "./common-types": "./src/lib/common-types.ts",
         "./confirm-dialog": "./src/components/confirm-dialog/index.ts",
+        "./cookie-consent": "./src/components/cookie-consent/index.ts",
         "./content": "./src/components/content/index.ts",
         "./dashboard-shell": "./src/components/dashboard-shell/index.ts",
         "./data-list": "./src/components/data-list/index.ts",

package/src/components/cookie-consent/CookieConsent.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, type HTMLAttributes } from 'vue';
+import { useI18n } from 'vue-i18n';
+import { Button } from '../ui/button';
+import { Card } from '../ui/card';
+import { cn } from '../../lib/utils';
+import { useCookieConsent } from './useCookieConsent';
+
+// Extra attributes go on the banner (the root is the Teleport)
+defineOptions({ inheritAttrs: false });
+
+// Props
+const props = withDefaults(defineProps<{
+    storageKey?: string;
+    message?: string;
+    policyTo?: string;
+    policyLabel?: string;
+    acceptLabel?: string;
+    declineLabel?: string;
+    class?: HTMLAttributes['class'];
+}>(), {
+    storageKey: 'cookieConsent',
+    message: undefined,
+    policyTo: undefined,
+    policyLabel: undefined,
+    acceptLabel: undefined,
+    declineLabel: undefined,
+    class: undefined
+});
+
+// Emits
+const emit = defineEmits<{
+    accept: [];
+    decline: [];
+}>();
+
+const { t } = useI18n();
+const { consent, accept, decline } = useCookieConsent(props.storageKey);
+const hasMounted = ref(false);
+
+// Shown in the browser only, until the visitor chooses (the stored choice is not known on the server)
+const isVisible = computed(() => hasMounted.value && consent.value === null);
+
+// Texts, with translated defaults
+const resolvedMessage = computed(() => props.message || t('uiVintage.cookieConsent.message'));
+const resolvedPolicyLabel = computed(() => props.policyLabel || t('uiVintage.cookieConsent.policy'));
+const resolvedAcceptLabel = computed(() => props.acceptLabel || t('uiVintage.cookieConsent.accept'));
+const resolvedDeclineLabel = computed(() => props.declineLabel || t('uiVintage.cookieConsent.decline'));
+
+// Save the choice and notify
+const handleAccept = () => {
+    accept();
+    emit('accept');
+};
+const handleDecline = () => {
+    decline();
+    emit('decline');
+};
+
+// Wait for the browser before showing the banner
+onMounted(() => {
+    hasMounted.value = true;
+});
+</script>
+
+<template>
+    <!-- Rendered in the body: a transformed or filtered ancestor (page transitions, reveal animations) would otherwise pin the fixed banner to itself instead of the viewport -->
+    <Teleport to="body">
+        <div v-if="isVisible" v-bind="$attrs" data-slot="cookie-consent" role="region" :aria-label="t('uiVintage.cookieConsent.region')" :class="cn('fixed inset-x-4 bottom-4 z-50 sm:left-auto sm:right-4 sm:max-w-md', props.class)">
+            <Card class="gap-3! p-4 shadow-elevated-sm">
+                <p class="text-sm text-foreground">
+                    {{ resolvedMessage }}
+                    <NuxtLinkLocale v-if="props.policyTo" :to="props.policyTo" class="font-bold underline underline-offset-2">{{ resolvedPolicyLabel }}</NuxtLinkLocale>
+                </p>
+                <div class="flex flex-wrap justify-end gap-2">
+                    <Button variant="secondary" size="sm" @click="handleDecline">{{ resolvedDeclineLabel }}</Button>
+                    <Button variant="primary" size="sm" @click="handleAccept">{{ resolvedAcceptLabel }}</Button>
+                </div>
+            </Card>
+        </div>
+    </Teleport>
+</template>

package/src/components/cookie-consent/index.ts

@@ -0,0 +1,3 @@
+export { default } from './CookieConsent.vue';
+export { default as CookieConsent } from './CookieConsent.vue';
+export { useCookieConsent, type CookieConsentValue } from './useCookieConsent';

package/src/components/cookie-consent/useCookieConsent.ts

@@ -0,0 +1,55 @@
+import { ref, type Ref } from 'vue';
+
+// The visitor's choice: 'granted', 'denied' or null (not asked yet)
+export type CookieConsentValue = 'granted' | 'denied' | null;
+
+// One shared state per storage key, so the banner and the code loading the scripts stay in sync (browser only)
+const consentStates = new Map<string, Ref<CookieConsentValue>>();
+
+// Read the stored choice (storage can be unavailable, e.g. blocked in private windows)
+const readStoredConsent = (storageKey: string): CookieConsentValue => {
+    try {
+        const value = localStorage.getItem(storageKey);
+        return value === 'granted' || value === 'denied' ? value : null;
+    } catch {
+        return null;
+    }
+};
+
+// Cookie consent state: gate optional scripts (analytics, ads) on `consent.value === 'granted'` and call `reset()` to ask again
+export const useCookieConsent = (storageKey = 'cookieConsent') => {
+    // On the server there is no stored choice (and no state must be shared between requests)
+    if (typeof window === 'undefined') {
+        const consent = ref<CookieConsentValue>(null);
+        const noop = () => {};
+        return { consent, accept: noop, decline: noop, reset: noop };
+    }
+
+    // Shared state for this key
+    let consent = consentStates.get(storageKey);
+    if (!consent) {
+        consent = ref(readStoredConsent(storageKey));
+        consentStates.set(storageKey, consent);
+    }
+
+    // Save a choice (null removes it, so the banner asks again)
+    const state = consent;
+    const setConsent = (value: CookieConsentValue) => {
+        state.value = value;
+        try {
+            if (value) {
+                localStorage.setItem(storageKey, value);
+            } else {
+                localStorage.removeItem(storageKey);
+            }
+        } catch { }
+    };
+
+    // Return the state and the actions
+    return {
+        consent: state,
+        accept: () => setConsent('granted'),
+        decline: () => setConsent('denied'),
+        reset: () => setConsent(null)
+    };
+};

package/src/components/ui/animated-number/AnimatedNumber.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from 'vue';
-import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { computed, getCurrentInstance, onBeforeMount, onBeforeUnmount, onMounted, ref, watch } from 'vue';
 import { cn } from '../../../lib/utils';
 
 // Props
@@ -22,8 +22,12 @@ const props = withDefaults(defineProps<{
     animateOnMount: true
 });
 
-const displayValue = ref(props.animateOnMount ? 0 : props.value);
+// The server always renders the final value (search engines, link previews and the first paint never see a 0), the count-up only runs for components created in the browser
+const isServer = typeof window === 'undefined';
+const displayValue = ref(props.animateOnMount && !isServer ? 0 : props.value);
 const direction = ref<'up' | 'down' | null>(null);
+const instance = getCurrentInstance();
+let isHydrated = false;
 let frame: number | null = null;
 
 // Format the displayed value
@@ -34,6 +38,9 @@ const formatter = computed(() => {
 });
 const formattedValue = computed(() => `${props.prefix}${formatter.value.format(displayValue.value)}${props.suffix}`);
 
+// Final value announced to screen readers from visually hidden text (the animated digits are hidden from them, and aria-label is not allowed on a span without a role)
+const accessibleValue = computed(() => `${props.prefix}${formatter.value.format(props.value)}${props.suffix}`);
+
 // Decelerating curve so the count settles gently on the final value
 const easeOutExpo = (progress: number) => progress === 1 ? 1 : 1 - Math.pow(2, -10 * progress);
 
@@ -70,9 +77,15 @@ const animateTo = (target: number) => {
 // Re-animate whenever the value changes
 watch(() => props.value, value => animateTo(value));
 
-// Count up on mount
+// When hydrating server HTML (the element already exists before the first render), keep the final value the server rendered, so there is no mismatch and no flash to 0
+onBeforeMount(() => {
+    isHydrated = !!instance?.vnode.el;
+    if (isHydrated) displayValue.value = props.value;
+});
+
+// Count up on mount (only for components created in the browser, server-rendered ones already show the final value)
 onMounted(() => {
-    if (props.animateOnMount) animateTo(props.value);
+    if (props.animateOnMount && !isHydrated) animateTo(props.value);
 });
 
 // Stop any pending frame
@@ -82,7 +95,8 @@ onBeforeUnmount(() => {
 </script>
 
 <template>
-    <span data-slot="animated-number" :data-direction="direction ?? undefined" :aria-label="`${props.prefix}${formatter.format(props.value)}${props.suffix}`" :class="cn('inline-block tabular-nums', props.class)">
+    <span data-slot="animated-number" :data-direction="direction ?? undefined" :class="cn('inline-block tabular-nums', props.class)">
         <span aria-hidden="true">{{ formattedValue }}</span>
+        <span class="sr-only">{{ accessibleValue }}</span>
     </span>
 </template>

package/src/i18n/de.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Benachrichtigungen"
         },
+        "cookieConsent": {
+            "region": "Cookie-Einwilligung",
+            "message": "Wir verwenden optionale Cookies, um zu verstehen, wie die Website genutzt wird. Sie werden nur gesetzt, wenn du zustimmst.",
+            "policy": "Cookie-Richtlinie",
+            "accept": "Akzeptieren",
+            "decline": "Ablehnen"
+        },
         "dataTable": {
             "selectAll": "Alle Zeilen auswählen",
             "selectRow": "Zeile auswählen"

package/src/i18n/en.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Notifications"
         },
+        "cookieConsent": {
+            "region": "Cookie consent",
+            "message": "We use optional cookies to understand how the site is used. They are only set if you accept.",
+            "policy": "Cookie policy",
+            "accept": "Accept",
+            "decline": "Decline"
+        },
         "dataTable": {
             "selectAll": "Select all rows",
             "selectRow": "Select row"

package/src/i18n/es.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Notificaciones"
         },
+        "cookieConsent": {
+            "region": "Consentimiento de cookies",
+            "message": "Usamos cookies opcionales para entender cómo se usa el sitio. Solo se instalan si aceptas.",
+            "policy": "Política de cookies",
+            "accept": "Aceptar",
+            "decline": "Rechazar"
+        },
         "dataTable": {
             "selectAll": "Seleccionar todas las filas",
             "selectRow": "Seleccionar fila"

package/src/i18n/fr.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Notifications"
         },
+        "cookieConsent": {
+            "region": "Consentement aux cookies",
+            "message": "Nous utilisons des cookies facultatifs pour comprendre comment le site est utilisé. Ils ne sont déposés que si vous acceptez.",
+            "policy": "Politique relative aux cookies",
+            "accept": "Accepter",
+            "decline": "Refuser"
+        },
         "dataTable": {
             "selectAll": "Sélectionner toutes les lignes",
             "selectRow": "Sélectionner la ligne"

package/src/i18n/it.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Notifiche"
         },
+        "cookieConsent": {
+            "region": "Consenso ai cookie",
+            "message": "Usiamo cookie facoltativi per capire come viene usato il sito. Vengono impostati solo se accetti.",
+            "policy": "Politica sui cookie",
+            "accept": "Accetta",
+            "decline": "Rifiuta"
+        },
         "dataTable": {
             "selectAll": "Seleziona tutte le righe",
             "selectRow": "Seleziona riga"

package/src/i18n/ja.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "通知"
         },
+        "cookieConsent": {
+            "region": "Cookieの同意",
+            "message": "サイトの利用状況を把握するため、任意のCookieを使用しています。同意した場合にのみ設定されます。",
+            "policy": "Cookieポリシー",
+            "accept": "同意する",
+            "decline": "拒否する"
+        },
         "dataTable": {
             "selectAll": "すべての行を選択",
             "selectRow": "行を選択"

package/src/i18n/pt.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Notificações"
         },
+        "cookieConsent": {
+            "region": "Consentimento de cookies",
+            "message": "Usamos cookies opcionais para entender como o site é usado. Eles só são definidos se você aceitar.",
+            "policy": "Política de cookies",
+            "accept": "Aceitar",
+            "decline": "Recusar"
+        },
         "dataTable": {
             "selectAll": "Selecionar todas as linhas",
             "selectRow": "Selecionar linha"

package/src/i18n/ru.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "Уведомления"
         },
+        "cookieConsent": {
+            "region": "Согласие на cookie",
+            "message": "Мы используем необязательные файлы cookie, чтобы понимать, как используется сайт. Они устанавливаются только с вашего согласия.",
+            "policy": "Политика cookie",
+            "accept": "Принять",
+            "decline": "Отклонить"
+        },
         "dataTable": {
             "selectAll": "Выбрать все строки",
             "selectRow": "Выбрать строку"

package/src/i18n/zh.json

@@ -118,6 +118,13 @@
         "toast": {
             "region": "通知"
         },
+        "cookieConsent": {
+            "region": "Cookie 同意",
+            "message": "我们使用可选的 Cookie 来了解网站的使用情况。只有在您同意后才会设置。",
+            "policy": "Cookie 政策",
+            "accept": "接受",
+            "decline": "拒绝"
+        },
         "dataTable": {
             "selectAll": "全选所有行",
             "selectRow": "选择行"