@brumaombra/ui-vintage 0.8.2 → 0.9.1

package/AGENTS.md

@@ -0,0 +1,41 @@
+# UI Vintage: instructions for AI agents
+
+These instructions are for agents that build UI in an app that depends on `@brumaombra/ui-vintage`, a Nuxt 4 component library with its own design tokens, motion system, and runtime flows. Reuse the library instead of building UI from scratch.
+
+## 1. Read the catalog first
+
+The complete API reference matching the installed version ships with the package:
+
+`node_modules/@brumaombra/ui-vintage/COMPONENTS.md`
+
+Search it (for example for `` ### `@brumaombra/ui-vintage/ ``, a component name, or a prop) instead of reading it top to bottom. It lists every entry point with its import line, components, props and defaults, events, slots, helpers, and examples. Never guess prop names: check them there.
+
+## 2. Choose the component
+
+Before writing a custom component, check the catalog's contents list. Common mappings:
+
+- Searchable select → `combobox` (`ComboboxSelect`); plain select → `select`.
+- Table with sorting or selection → `data-table`; KPI tiles → `single-value-card`; a compact row of numbers → `stat-strip`.
+- Confirmation → `showConfirmDialog` (`confirm-dialog`); notification → `showMessageToast` (`message-toast`); blocking load → `setBusy` (`busy-indicator`). These mount themselves, so don't add them to a template.
+- App layout with a sidebar → `dashboard-shell`; marketing or blog layout → `landing`; page title row → `page-header`.
+- Empty and loading placeholders → `empty-state-card`, `loading-state-card`, `skeleton`.
+- Blog pages with Nuxt Content → `blog` (`BlogHeaderSection`, `BlogPostHeader`, `PostsList`, `TableOfContents`, `BlogContentRenderer`, ...).
+
+Only build something new when no entry point fits, and compose it from library primitives (`card`, `button`, `field`, ...).
+
+## 3. Follow the library conventions
+
+- Import from explicit subpaths: `import { Button } from '@brumaombra/ui-vintage/button'`. Never import from `@brumaombra/ui-vintage/src/...`.
+- Style with the semantic tokens (`bg-background`, `bg-card`, `bg-surface`, `bg-accent`, `bg-primary`, `text-foreground`, `text-muted-foreground`, `border-border`, `border-border-strong`, ...). They adapt to dark mode, so don't write `dark:` color variants or hard-coded colors for surfaces and text.
+- Customize components through their props and the `class` prop (merged with tailwind-merge) rather than wrapping them in extra styled elements.
+- Keep corners at `rounded` (the library's square look) and use `shadow-elevated-sm|md|lg|xl` for elevation, without glows or gradients.
+- For motion, reuse the library utilities (`ease-spring`, `ease-out-expo`, `animate-uv-fade-up`, `animate-uv-pop`, `uv-floating-motion`). In custom transitions, name `scale`, `rotate`, and `translate` explicitly; Tailwind v4 doesn't animate them through `transform`.
+- Icons are Hugeicons definitions: import each one from its own module (`import Rocket01Icon from '@hugeicons/core-free-icons/Rocket01Icon'`, never the `@hugeicons/core-free-icons` barrel, which makes the build parse the whole icon set) and pass them to `:icon` props, or render them with `HugeiconsIcon` from `@hugeicons/vue`. Both packages are peer dependencies, so the app must list them in its own `package.json`.
+- Form controls use `v-model`. Mark invalid fields with `aria-invalid` and show messages with `FieldError`.
+- Library strings are translated through vue-i18n (`uiVintage.*` keys). App copy belongs in the app's own locale files.
+
+## 4. Check your work
+
+- Every import path you used appears as an entry point in `COMPONENTS.md`.
+- Every prop and event you used appears in that component's table.
+- No new CSS reimplements something a component or token already provides.

package/COMPONENTS.md

@@ -9,15 +9,15 @@ This file lists every public entry point of the package with its components, pro
 - Register the Nuxt module once in `nuxt.config`: `modules: ['@brumaombra/ui-vintage']`. It injects the stylesheet, installs `@nuxt/image`, and merges the library translations into vue-i18n.
 - Import from explicit subpaths only (for example `@brumaombra/ui-vintage/button`). There is no root barrel, and `src/` paths are internal.
 - Style with the semantic Tailwind tokens: `bg-background`, `bg-card`, `bg-surface`, `bg-accent`, `bg-primary`, `hover:bg-primary-hover`, `text-foreground`, `text-muted-foreground`, `border-border`, `border-border-strong`, `text-destructive`, `text-success`, `text-warning`, `text-info`. They switch automatically in dark mode, so do not add `dark:` color overrides.
-- Reuse the motion utilities from the stylesheet instead of custom animations: `ease-spring`, `ease-bounce`, `ease-out-expo`, `ease-snappy`, `uv-floating-motion`, `uv-modal-motion`, `uv-overlay-motion`, `uv-collapsible-motion`, `uv-field`, `animate-uv-pop`, `animate-uv-fade-up`, `animate-uv-shake`, `animate-uv-shimmer`, `animate-uv-float`, `animate-uv-ping-soft`, and elevation via `shadow-elevated-sm|md|lg|xl` and `shadow-glow`. Tailwind v4 animates `scale`, `rotate`, and `translate` as separate properties, so name them (not `transform`) in custom transitions.
-- Icons are Hugeicons definitions passed as values: `import { Rocket01Icon } from '@hugeicons/core-free-icons'` then `:icon="Rocket01Icon"`, or render one with `<HugeiconsIcon :icon="Rocket01Icon" />` from `@hugeicons/vue`.
+- Reuse the motion utilities from the stylesheet instead of custom animations: `ease-spring`, `ease-bounce`, `ease-out-expo`, `ease-snappy`, `uv-floating-motion`, `uv-modal-motion`, `uv-overlay-motion`, `uv-collapsible-motion`, `uv-field`, `animate-uv-pop`, `animate-uv-fade-up`, `animate-uv-shake`, `animate-uv-shimmer`, `animate-uv-float`, `animate-uv-ping-soft`, and elevation via `shadow-elevated-sm|md|lg|xl`. Tailwind v4 animates `scale`, `rotate`, and `translate` as separate properties, so name them (not `transform`) in custom transitions.
+- Icons are Hugeicons definitions passed as values, each imported from its own module: `import Rocket01Icon from '@hugeicons/core-free-icons/Rocket01Icon'` then `:icon="Rocket01Icon"`, or render one with `<HugeiconsIcon :icon="Rocket01Icon" />` from `@hugeicons/vue`.
 - Every component accepts `class`, merged with `tailwind-merge`, so utility overrides win over the defaults.
 
 ## Contents
 
 - **Actions:** [button](#brumaombraui-vintagebutton), [dropdown-menu](#brumaombraui-vintagedropdown-menu), [kbd](#brumaombraui-vintagekbd), [load-more-button](#brumaombraui-vintageload-more-button), [text-link](#brumaombraui-vintagetext-link), [toggle-group](#brumaombraui-vintagetoggle-group)
 - **Forms:** [calendar](#brumaombraui-vintagecalendar), [checkbox](#brumaombraui-vintagecheckbox), [combobox](#brumaombraui-vintagecombobox), [date-picker](#brumaombraui-vintagedate-picker), [date-time-picker](#brumaombraui-vintagedate-time-picker), [field](#brumaombraui-vintagefield), [file-dropzone](#brumaombraui-vintagefile-dropzone), [input](#brumaombraui-vintageinput), [label](#brumaombraui-vintagelabel), [native-select](#brumaombraui-vintagenative-select), [number-field](#brumaombraui-vintagenumber-field), [pin-input](#brumaombraui-vintagepin-input), [radio-group](#brumaombraui-vintageradio-group), [select](#brumaombraui-vintageselect), [slider](#brumaombraui-vintageslider), [slider-form-component](#brumaombraui-vintageslider-form-component), [switch](#brumaombraui-vintageswitch), [switch-form-component](#brumaombraui-vintageswitch-form-component), [tags-input](#brumaombraui-vintagetags-input), [textarea](#brumaombraui-vintagetextarea), [time-picker](#brumaombraui-vintagetime-picker)
-- **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)
+- **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), [stat-strip](#brumaombraui-vintagestat-strip), [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), [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)
@@ -31,7 +31,7 @@ Buttons, segmented controls, menus, and keyboard hints.
 
 ### `@brumaombra/ui-vintage/button`
 
-Button with solid, outline, ghost, link, and tone variants. Spring press feedback, a sheen on primary buttons, and a `loading` state that keeps the width stable. Use `as-child` to render a link.
+Button with primary, secondary, ghost, link, and tone variants. Spring press feedback and a `loading` state that keeps the width stable. Use `as-child` to render a link.
 
 ```ts
 import { Button, buttonVariants } from '@brumaombra/ui-vintage/button';
@@ -56,6 +56,7 @@ import type { ButtonVariants } from '@brumaombra/ui-vintage/button';
 | `variant` | `ButtonVariants['variant']` |  |
 | `size` | `ButtonVariants['size']` |  |
 | `loading` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
 | `class` | `HTMLAttributes['class']` |  |
 
 - **Also accepts** all props of Reka `PrimitiveProps`.
@@ -334,7 +335,7 @@ const toggleGroupContextKey: InjectionKey<{ size: Ref<ToggleGroupSize>; indicato
 
 ## Forms
 
-Inputs, pickers, and form layout. Text-like controls share the `uv-field` focus glow and shake on `aria-invalid`.
+Inputs, pickers, and form layout. Text-like controls share the `uv-field` focus ring and shake on `aria-invalid`.
 
 ### `@brumaombra/ui-vintage/calendar`
 
@@ -625,7 +626,7 @@ import { DateTimePicker } from '@brumaombra/ui-vintage/date-time-picker';
 Form layout primitives: label, description, error list, groups, and fieldsets. `FieldError` accepts strings or `{ message }` objects and hides itself when empty.
 
 ```ts
-import { fieldVariants, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle } from '@brumaombra/ui-vintage/field';
+import { fieldVariants, useFieldControlId, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle } from '@brumaombra/ui-vintage/field';
 import type { FieldVariants } from '@brumaombra/ui-vintage/field';
 ```
 
@@ -707,6 +708,7 @@ import type { FieldVariants } from '@brumaombra/ui-vintage/field';
 ```ts
 type FieldVariants = { orientation?: 'vertical' | 'horizontal' | 'responsive' | null | undefined }
 const fieldVariants: (props?: FieldVariants & ClassProp) => string
+function useFieldControlId(explicitId?: () => string | undefined)
 ```
 
 ---
@@ -1049,7 +1051,11 @@ import { Slider } from '@brumaombra/ui-vintage/slider';
 
 #### `Slider`
 
-- **Props:** `class`.
+| Prop | Type | Default |
+| --- | --- | --- |
+| `thumbLabel` | `string` |  |
+| `class` | `HTMLAttributes['class']` |  |
+
 - **Also accepts** all props of Reka `SliderRootProps`.
 - **Emits:** all events of Reka `SliderRootEmits`.
 
@@ -1201,7 +1207,7 @@ import { TimePicker } from '@brumaombra/ui-vintage/time-picker';
 | --- | --- | --- |
 | `defaultValue` | `string` | `''` |
 | `modelValue` | `string` |  |
-| `step` | `string \| number` | `1` |
+| `step` | `string \| number` | `60` |
 | `min` | `string` |  |
 | `max` | `string` |  |
 | `disabled` | `boolean` | `false` |
@@ -1334,7 +1340,7 @@ import { Badge } from '@brumaombra/ui-vintage/badge';
 
 ### `@brumaombra/ui-vintage/card`
 
-Surface container with header, title, description, content, footer, and action slots. `interactive` adds a hover lift and pointer spotlight; `color` switches to a tone surface.
+Surface container with header, title, description, content, footer, and action slots. `interactive` adds a gentle hover lift with a stronger shadow; `color` switches to a tone surface.
 
 ```ts
 import { Card, CardAction, CardContent, CardText, CardDescription, CardFooter, CardHeader, CardTitle } from '@brumaombra/ui-vintage/card';
@@ -1516,7 +1522,7 @@ import type { DataTableSortDirection, DataTableSort, DataTableColumn } from '@br
 | `stickyHeader` | `boolean` | `false` |
 | `class` | `HTMLAttributes['class']` |  |
 
-- **Emits:** `update:selected` (value: PropertyKey[]), `update:sort` (value: DataTableSort \| null), `row-click` (row: T, event: MouseEvent).
+- **Emits:** `update:selected` (value: PropertyKey[]), `update:sort` (value: DataTableSort \| null), `row-click` (row: T, event: MouseEvent \| KeyboardEvent).
 - **Slots:** `cell-${string}`, `header-${string}`, `empty`.
 
 #### Functions, constants, and types
@@ -1682,6 +1688,32 @@ import { Skeleton } from '@brumaombra/ui-vintage/skeleton';
 
 ---
 
+### `@brumaombra/ui-vintage/stat-strip`
+
+Compact row of stats in one bordered strip, each with an optional icon. Numeric values count up like `AnimatedNumber`.
+
+```ts
+import { StatStrip } from '@brumaombra/ui-vintage/stat-strip';
+```
+
+```vue
+<StatStrip :items="[
+    { icon: News01Icon, value: 6, label: 'posts' },
+    { icon: FolderLibraryIcon, value: 5, label: 'categories' },
+    { icon: Tag01Icon, value: 11, label: 'tags' }
+]" />
+```
+
+#### `StatStrip`
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `items` *(required)* | `Array<{ label: string; value: string \| number; icon?: HugeiconsIconDefinition; formatOptions?: Intl.NumberFormatOptions }>` |  |
+| `animate` | `boolean` | `true` |
+| `class` | `HTMLAttributes['class']` |  |
+
+---
+
 ### `@brumaombra/ui-vintage/table`
 
 Low-level table parts (header, body, row, cell, caption, footer, empty row) for fully custom tables.
@@ -1769,7 +1801,7 @@ import { Accordion } from '@brumaombra/ui-vintage/accordion';
 | `class` | `HTMLAttributes['class']` |  |
 
 - **Emits:** `update:open` (value: boolean).
-- **Slots:** `default`.
+- **Slots:** `trailing`, `default`.
 
 ---
 
@@ -2081,7 +2113,7 @@ import type { SidebarProps, SidebarMenuButtonVariants } from '@brumaombra/ui-vin
 
 | Prop | Type | Default |
 | --- | --- | --- |
-| `defaultOpen` | `boolean` | `!defaultDocument?.cookie.includes(`${SIDEBAR_COOKIE_NAME}=false`)` |
+| `defaultOpen` | `boolean` | `undefined` |
 | `open` | `boolean` | `undefined` |
 | `compact` | `boolean` | `false` |
 | `class` | `HTMLAttributes['class']` |  |
@@ -2357,6 +2389,7 @@ import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, Comma
 | --- | --- | --- |
 | `class` | `HTMLAttributes['class']` |  |
 | `heading` | `string` |  |
+| `stagger` | `boolean` |  |
 
 - **Also accepts** all props of Reka `ListboxGroupProps`.
 - **Slots:** `default`.
@@ -3045,6 +3078,7 @@ import { DashboardShell } from '@brumaombra/ui-vintage/dashboard-shell';
 | --- | --- | --- |
 | `appName` | `string` | `''` |
 | `appLogo` | `string` | `''` |
+| `appLogoDark` | `string` | `''` |
 | `appLinkTo` | `string` | `'/'` |
 | `title` | `string` | `''` |
 | `description` | `string` | `''` |
@@ -3122,6 +3156,7 @@ import type { LandingFooterLink, LandingFooterSection } from '@brumaombra/ui-vin
 | --- | --- | --- |
 | `appName` | `string` | `''` |
 | `appLogo` | `string` | `''` |
+| `appLogoDark` | `string` | `''` |
 | `appLinkTo` | `string` | `'/'` |
 | `logoClass` | `HTMLAttributes['class']` |  |
 | `class` | `HTMLAttributes['class']` |  |
@@ -3138,6 +3173,7 @@ import type { LandingFooterLink, LandingFooterSection } from '@brumaombra/ui-vin
 | --- | --- | --- |
 | `appName` *(required)* | `string` |  |
 | `appLogo` | `string` |  |
+| `appLogoDark` | `string` |  |
 | `appLinkTo` | `string` | `'/'` |
 | `logoClass` | `HTMLAttributes['class']` |  |
 | `appDescription` | `string` | `''` |
@@ -3147,7 +3183,7 @@ import type { LandingFooterLink, LandingFooterSection } from '@brumaombra/ui-vin
 | `authorLink` | `string` | `''` |
 | `year` | `number` | `new Date().getFullYear()` |
 | `showBottomBar` | `boolean` | `true` |
-| `level` | `HeadingLevel` | `3` |
+| `level` | `HeadingLevel` | `2` |
 | `class` | `HTMLAttributes['class']` |  |
 | `containerClass` | `HTMLAttributes['class']` |  |
 | `brandClass` | `HTMLAttributes['class']` |  |
@@ -3203,6 +3239,7 @@ import type { LandingFooterLink, LandingFooterSection } from '@brumaombra/ui-vin
 | --- | --- | --- |
 | `appName` *(required)* | `string` |  |
 | `appLogo` | `string` |  |
+| `appLogoDark` | `string` |  |
 | `appLinkTo` | `string` | `'/'` |
 | `logoClass` | `HTMLAttributes['class']` |  |
 | `appDescription` | `string` | `''` |
@@ -3212,7 +3249,7 @@ import type { LandingFooterLink, LandingFooterSection } from '@brumaombra/ui-vin
 | `authorLink` | `string` | `''` |
 | `year` | `number` | `new Date().getFullYear()` |
 | `showBottomBar` | `boolean` | `true` |
-| `level` | `HeadingLevel` | `3` |
+| `level` | `HeadingLevel` | `2` |
 | `class` | `HTMLAttributes['class']` |  |
 | `containerClass` | `HTMLAttributes['class']` |  |
 | `brandClass` | `HTMLAttributes['class']` |  |
@@ -3252,6 +3289,7 @@ import { LandingNavbar } from '@brumaombra/ui-vintage/landing-navbar';
 | --- | --- | --- |
 | `appName` | `string` | `''` |
 | `appLogo` | `string` | `''` |
+| `appLogoDark` | `string` | `''` |
 | `appLinkTo` | `string` | `'/'` |
 | `logoClass` | `HTMLAttributes['class']` |  |
 | `class` | `HTMLAttributes['class']` |  |
@@ -3291,7 +3329,7 @@ import { LandingShell } from '@brumaombra/ui-vintage/landing-shell';
 Flag icons for the supported locales.
 
 ```ts
-import { LanguageFlag, EnglishFlag, FrenchFlag, GermanFlag, ItalianFlag, ChineseFlag, JapaneseFlag, RussianFlag, SpanishFlag } from '@brumaombra/ui-vintage/language-flag';
+import { LanguageFlag, EnglishFlag, FrenchFlag, GermanFlag, ItalianFlag, ChineseFlag, JapaneseFlag, PortugueseFlag, RussianFlag, SpanishFlag } from '@brumaombra/ui-vintage/language-flag';
 import type { SupportedLanguageCode } from '@brumaombra/ui-vintage/language-flag';
 ```
 
@@ -3325,6 +3363,10 @@ import type { SupportedLanguageCode } from '@brumaombra/ui-vintage/language-flag
 
 - **Props:** none.
 
+#### `PortugueseFlag`
+
+- **Props:** none.
+
 #### `RussianFlag`
 
 - **Props:** none.
@@ -3424,10 +3466,10 @@ Components for Nuxt Content pages and a complete blog.
 
 ### `@brumaombra/ui-vintage/blog`
 
-Blog building blocks: an animated hero header, a full-bleed featured carousel, post and category cards, tags, table of contents, reading progress, FAQ, share sidebar, and the content renderer. Scroll entrances use AOS: install `aos` in the app and initialize it (the components carry `data-aos="blur-up"`, and the library stylesheet defines that animation). Without AOS the content simply renders without entrances.
+Blog building blocks: an animated hero header, a post header (breadcrumbs, category and tags, title, author line, and featured image), a full-bleed featured carousel, post and category cards, tags, table of contents, reading progress, FAQ, share sidebar, and the content renderer. Scroll entrances use AOS: install `aos` in the app and initialize it (the components carry `data-aos="blur-up"`, and the library stylesheet defines that animation). Without AOS the content simply renders without entrances.
 
 ```ts
-import { AllPostsSection, BlogContentRenderer, BlogFAQSection, BlogInfoSection, BlogHeaderSection, BlogSectionTitle, BlogTagsSection, CategoriesList, CategoriesSection, CategoryCard, HeaderCarousel, PostCard, PostsList, SocialShareSidebar, TableOfContents } from '@brumaombra/ui-vintage/blog';
+import { AllPostsSection, BlogContentRenderer, BlogFAQSection, BlogInfoSection, BlogPostHeader, BlogHeaderSection, BlogSectionTitle, BlogTagsSection, CategoriesList, CategoriesSection, CategoryCard, HeaderCarousel, PostCard, PostsList, SocialShareSidebar, TableOfContents } from '@brumaombra/ui-vintage/blog';
 ```
 
 #### `AllPostsSection`
@@ -3462,16 +3504,42 @@ import { AllPostsSection, BlogContentRenderer, BlogFAQSection, BlogInfoSection,
 | `author` *(required)* | `string` |  |
 | `authorUrl` *(required)* | `string` |  |
 | `authorImageUrl` *(required)* | `string` |  |
+| `authorBio` | `string` | `''` |
 | `datePublished` *(required)* | `string` |  |
 | `dateModified` | `string \| null` | `null` |
 
+#### `BlogPostHeader`
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `title` *(required)* | `string` |  |
+| `description` | `string` | `''` |
+| `image` | `string` | `''` |
+| `author` | `string` | `''` |
+| `authorImageUrl` | `string` | `''` |
+| `datePublished` | `string` | `''` |
+| `categoryText` | `string` | `''` |
+| `categorySlug` | `string` | `''` |
+| `tags` | `Array<{ name: string; slug: string }>` | `[]` |
+| `body` | `unknown` |  |
+| `readingMinutes` | `number \| null` | `null` |
+| `blogPath` | `string` | `'/blog'` |
+| `blogLabel` | `string` | `''` |
+| `animated` | `boolean` | `true` |
+
+- **Slots:** `meta`, `media`.
+
 #### `BlogHeaderSection`
 
 | Prop | Type | Default |
 | --- | --- | --- |
 | `badges` | `Array<{ color: ToneColor; text: string }>` | `[]` |
+| `announcement` | `{ text: string; to: string; label?: string } \| null` | `null` |
 | `title` *(required)* | `string` |  |
+| `highlight` | `string` | `''` |
 | `description` *(required)* | `string` |  |
+| `stats` | `Array<{ label: string; value: string \| number; icon?: HugeiconsIconDefinition }>` | `[]` |
+| `align` | `'left' \| 'center' \| 'right'` | `'center'` |
 
 #### `BlogSectionTitle`
 
@@ -3487,6 +3555,7 @@ import { AllPostsSection, BlogContentRenderer, BlogFAQSection, BlogInfoSection,
 | Prop | Type | Default |
 | --- | --- | --- |
 | `tags` | `Array<{ name: string; slug: string; count: number }>` | `[]` |
+| `blogPath` | `string` | `'/blog'` |
 
 #### `CategoriesList`
 
@@ -3576,6 +3645,7 @@ import { Terminal, CodeBlock, ProsePre, BlogList, BlogTable, Flow, ProseHr } fro
 | --- | --- | --- |
 | `code` | `string` | `''` |
 | `language` | `string` | `''` |
+| `filename` | `string` | `''` |
 
 - **Slots:** `default`.
 
@@ -3635,7 +3705,7 @@ type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
 Class merging (`cn`) and formatting helpers.
 
 ```ts
-import { cn, formatDateLongItalyTimezone } from '@brumaombra/ui-vintage/utils';
+import { cn, formatDateLongItalyTimezone, getReadingMinutes } from '@brumaombra/ui-vintage/utils';
 ```
 
 #### Functions, constants, and types
@@ -3643,4 +3713,5 @@ import { cn, formatDateLongItalyTimezone } from '@brumaombra/ui-vintage/utils';
 ```ts
 function cn(...inputs: ClassValue[])
 function formatDateLongItalyTimezone(date: string | number | Date | null | undefined, locale: string)
+function getReadingMinutes(content: unknown, wordsPerMinute = 220)
 ```