VD Framework 4 - Complete Reference

⚙️ Required Load Order

<script src="vd_framework_utils.js"></script>  <script src="vd_framework_theme.js"></script>  <script src="vd_framework_global.js"></script>  <script src="vd_framework_macrocomponents.js"></script> 

⚠️ All paths must be relative (no leading '/') — folder-agnostic, relative to the HTML file.

📖 Legend

Attributes: HTML attributes for the component Dependencies: Required parent/child None: Standalone NEW Added in v4 role=… ARIA role --vd-* CSS variable consumed

Component	Attributes	Description	ARIA & Keyboard (v4)	Dependencies / Notes
🎨 THEME SYSTEM NEW v4
<vd-theme> NEW	• primary (color) • secondary (color) • background (color) • surface (color) • text (color) • border (color) • radius (e.g. 8px) • shadow (box-shadow value) • font-family • transition (e.g. 0.2s ease) • success / error / warning / info	Injects `--vd-*` CSS custom properties into `:root`. All VD components consume these tokens automatically. Place before any VD component in `<body>`.	No interactive role. Programmatic API: `VdTheme.applyTokens({…})`, `VdTheme.getVar("primary")`	None — standalone. Loaded via `vd_framework_theme.js`
🧭 NAVIGATION COMPONENTS
<vd-radionav>	• backgroundcolor • align (left/center/right) • textcolor	Navigation container styled as a radio-button group. Manages active state across child links.	role=radiogroup aria-label v4: ARIA radiogroup semantics	Requires `<vd-radiolink>` children
<vd-radiolink>	• url (link destination) • textcolor • activecolor • shadowcolor • backgroundcolor • active (true/false) • show-radio (true/false)	Individual radio-style navigation link. Handles click, sets `active`, navigates to `url`.	role=radio aria-checked (synced) tabindex Keyboard: Enter/Space selects v4: full ARIA radio semantics	Must be child of `<vd-radionav>`
<vd-popnav>	• backgroundcolor • shadowcolor • align	Horizontal navigation bar with pop-up (lift) hover effect on links.	role=navigation aria-label v4: landmark navigation	Requires `<vd-poplink>` children
<vd-poplink>	• url • target (_self/_blank) • textcolor • hovercolor	Individual link for popnav with hover lift animation.	role=menuitem Keyboard: Enter activates v4: menuitem role	Must be child of `<vd-popnav>`
<vd-skewnav>	• backgroundcolor • shadowcolor • align	Navigation bar with italic/skewed link style.	role=navigation aria-label v4: landmark navigation	Requires `<vd-skewlink>` children
<vd-skewlink>	• url • target • skewcolor • textcolor • hovercolor	Skewed/slanted link button for skewnav.	role=menuitem Keyboard: Enter activates v4: menuitem role	Must be child of `<vd-skewnav>`
🏗️ LAYOUT COMPONENTS
<vd-structure>	• orientation (portrait/landscape) • backgroundcolor • textcolor • shadowcolor • width • height	Two-panel layout container (side + main). `landscape` = side-by-side; `portrait` = stacked.	—	Use with `<vd-sidepanel>` + `<vd-mainpanel>`
<vd-mainpanel>	• backgroundcolor • textcolor • width	Primary content panel inside `<vd-structure>`.	—	Must be inside `<vd-structure>`
<vd-sidepanel>	• backgroundcolor • textcolor • width	Secondary/sidebar panel inside `<vd-structure>`.	—	Must be inside `<vd-structure>`
<vd-sp>	• bordercolor • width	Bordered section/panel with subtle separation styling.	—	None
<vd-spacer>	• height (e.g. 20px)	Vertical spacer block.	—	None
<vd-left>	—	Aligns child content to the left.	—	None
<vd-right>	—	Aligns child content to the right.	—	None
<vd-center>	—	Centers child content.	—	None
🖼️ UI DISPLAY COMPONENTS
<vd-colorcard>	• backgroundcolor • textcolor • shadowcolor • imgsrc • imgwidth • imgheight • width	Card with customizable background, optional top image, and slotted content.	—	None
<vd-colorbadge>	• backgroundcolor • textcolor • shadowcolor • imgsrc • imgwidth / imgheight • width	Compact badge/chip component with optional icon image.	—	None
<vd-pill>	• backgroundcolor • textcolor	Small pill/tag for status labels or categories.	—	None
<vd-accordion>	• title (header text) • backgroundcolor • textcolor • extend (vertical/horizontal) • width • headheight --vd-border, --vd-radius, --vd-shadow, --vd-transition	Collapsible content panel. Click header to toggle open/closed.	role=button on header aria-expanded (synced) Keyboard: Enter/Space toggles v4: ARIA expanded state	None
<vd-alert>	• backgroundcolor • textcolor • bordercolor • icon	Alert/notification banner for status messages.	role=alert aria-live=assertive v4: live region	None
<vd-confirmation>	• title • backgroundcolor • textcolor • confirm-label • cancel-label	Modal confirmation dialog with confirm/cancel actions.	role=dialog aria-modal=true aria-labelledby v4: modal dialog semantics	None
👍 FEEDBACK COMPONENTS
<vd-like>	• backgroundcolor • textcolor • hovercolor • shadowcolor • image (icon src) --vd-success, --vd-transition	Like / upvote toggle button with animated counter. Fires `vd-like-toggle` custom event.	role=button aria-label="Like" aria-pressed (synced) v4: pressed state + --vd-success color	None
<vd-dislike>	• backgroundcolor • textcolor • hovercolor • shadowcolor • image --vd-error, --vd-transition	Dislike / downvote toggle button. Fires `vd-dislike-toggle` custom event.	role=button aria-label="Dislike" aria-pressed (synced) v4: pressed state + --vd-error color	None
📊 TABLE COMPONENTS
<vd-table>	• border (px) • width • height	Styled data table container with sortable column support.	—	Use with `<vd-tr>`, `<vd-th>`, `<vd-td>`
<vd-tr>	—	Table row.	—	Inside `<vd-table>`
<vd-th>	• sortable (boolean attr)	Table header cell. Add `sortable` for click-to-sort.	—	Inside `<vd-tr>`
<vd-td>	—	Table data cell.	—	Inside `<vd-tr>`
🔤 TYPOGRAPHY COMPONENTS
<vd-bi>	—	Bold + italic inline text.	—	None
<vd-bu>	—	Bold + underlined inline text.	—	None
<vd-iu>	—	Italic + underlined inline text.	—	None
📈 VISUALIZATION COMPONENTS — vd_framework_macrocomponents.js
<vd-timeline>	• title • backgroundcolor • textcolor • shadowcolor • width	Vertical timeline container. Title is displayed at the top.	role=list aria-label (from title) v4: semantic list	Requires `<vd-timeline-item>` children
<vd-timeline-item>	• date • title • backgroundcolor • textcolor	Single event entry in a timeline.	role=listitem v4: semantic listitem	Must be inside `<vd-timeline>`
<vd-progresscircle>	• value (0–100) • color (stroke color; default: --vd-primary) • width (e.g. 150px)	Circular SVG progress indicator.	role=progressbar aria-valuenow/min/max v4: progressbar + --vd-primary default	None
<vd-countdown>	• end (ISO 8601 datetime) • backgroundcolor • textcolor	Live countdown to a target date, showing days/hours/minutes/seconds.	role=timer aria-label v4: timer role	None
🗂️ TAB COMPONENTS — vd_framework_macrocomponents.js
<vd-tabcontrol>	• backgroundcolor • textcolor • activecolor --vd-border	Tab container. Manages active tab state across `<vd-tab>` children.	role=tablist aria-label="Tabs" v4: tablist semantics	Requires `<vd-tab>` children
<vd-tab>	• label (tab header text) • active (true/false)	Individual tab panel. Only the active tab is visible.	role=tab aria-selected (synced) tabindex v4: tab role + selected sync	Must be inside `<vd-tabcontrol>`
🎠 CAROUSEL — vd_framework_macrocomponents.js
<vd-carousel>	• width • height • speed (ms) • direction (left/right) • stoponhover (true/false) • backgroundcolor	Auto-rotating content carousel. Accepts any child elements (images, cards, etc.).	role=region aria-roledescription=carousel aria-label v4: carousel region	None
💬 CHAT COMPONENTS — vd_framework_macrocomponents.js
<vd-chatbox>	• backgroundcolor • textcolor • shadowcolor • width	Static chat message container for displaying conversation threads.	role=log aria-live=polite v4: live log region	Use with `<vd-chatline>`
<vd-chatline>	• user (display name)	Single chat message line with user label.	—	Inside `<vd-chatbox>`
<vd-inputbox>	• placeholder • backgroundcolor • textcolor • buttoncolor	Text input area with send button. Fires `vd-send` event on submit.	aria-label on textarea v4: labelled input	None — standalone
🤖 AI COMPONENTS — vd_framework_macrocomponents.js
<vd-chatbot>	• title • backgroundcolor • textcolor • width • height • model (GPT model ID)	Full GPT-4 chat interface. Communicates via `openai_proxy.php` — API key stays server-side.	Chat history: role=log v4: secure proxy + log role	Requires `openai_proxy.php` on same server. Security v4
<vd-dalle>	• title • backgroundcolor • textcolor • width	DALL-E 3 image generation interface. Displays prompt input and generated images. Uses `openai_proxy.php`.	History panel: role=log v4: secure proxy + log role	Requires `openai_proxy.php`. Security v4
🎬 MEDIA COMPONENTS — vd_framework_macrocomponents.js
<vd-video>	• file (video URL or path) • title (display title) • backgroundcolor • textcolor • bordercolor • fullscreen (boolean attr — set to `"true"` to trigger fullscreen)	Styled HTML5 video player with custom play/seek controls. Phase 6: added fullscreen support via button and JS API. `element.enterFullscreen()` — programmatic fullscreen trigger. Setting `fullscreen="true"` attribute also triggers fullscreen. Fires `vd-fullscreen` event on activation.	`vd-fullscreen` — on fullscreen activation	None
<vd-music>	• src (audio URL) • autoplay (true/false) • loop (true/false) • backgroundcolor • textcolor	Styled HTML5 audio player with custom controls.	—	None
📅 PLANNER COMPONENT — vd_framework_macrocomponents.js
<vd-planner>	• backgroundcolor • textcolor • width • backend (path to calendar-backend.php)	Full calendar/planner with add, edit, delete tasks. Persists via PHP backend.	—	Requires `calendar-backend.php` + writable `tasks.json`

🆕 Phase 6 — New Components

Five new base components added to vd_framework_global.js, plus vd-video updated with fullscreen support.

Tag	Attributes	Description & Events	Example
<vd-button>	label — button text (fallback if no slot content) href — renders as <a> when set, <button> otherwise target — link target (_self/_blank, default _self) variant — `primary` \| `secondary` \| `ghost` size — `sm` \| `md` \| `lg` backgroundcolor — fill color (primary) or border/text color (secondary/ghost) textcolor — text color on filled button hovercolor — hover background color icon — emoji or character prepended to label type — `button` \| `submit` (when used in forms) disabled — boolean, disables click and applies 50% opacity	Generic CTA button. Works as link (<a>) or native button element depending on `href`. Slot content overrides `label` — put styled HTML inside the tag for custom content. Events fired: `vd-click` — `{element, label, href}` — fires on every click (bubbles, composed) JS example: `document.querySelector('vd-button').addEventListener('vd-click', e => console.log(e.detail));`	<vd-button label="Register" href="register.php" variant="primary" size="lg"></vd-button> <vd-button variant="secondary" backgroundcolor="#667eea">Learn More</vd-button> <vd-button type="submit" icon="🚀">Send</vd-button>
<vd-chip>	label — chip text (fallback if no slot content) backgroundcolor — chip background textcolor — chip text color bordercolor — border color icon — emoji/character before label removable — boolean; shows × button and allows removal	Lightweight inline tag/badge. Lighter than `vd-pill` — no image, no profile context. Use for feature tags, status badges, filter chips, keyword tags. Events fired: `vd-chip-click` — `{element, label}` — on chip body click `vd-chip-remove` — `{element, label}` — on × button click → cancelable: call `e.preventDefault()` to prevent auto-removal from DOM	<vd-chip label="Token Illimitati" icon="♾️"></vd-chip> <vd-chip label="React" removable backgroundcolor="#e8f0fe" textcolor="#1a73e8"></vd-chip> document.querySelectorAll('vd-chip').forEach(c => c.addEventListener('vd-chip-remove', e => console.log('removed:', e.detail.label)));
<vd-hero>	title — h1 headline; wrap words with `word` for accent color subtitle — paragraph below title eyebrow — small label above title imgsrc — hero image URL (optional) imgalt — img alt text (default: "Hero image") backgroundcolor — section background textcolor — base text color accentcolor — color for accent words in title padding — inner padding (default: 80px 2rem 60px)	Full-page hero section: eyebrow → headline → subtitle → badges → CTA → image. Named slots: `slot="badges"` — renders in a flexbox row (use <vd-chip> elements here) `slot="cta"` — primary CTA area (use <vd-button> here) Default slot — appended after image (for extra content) Accent syntax: `title="Da Idea ad App in 60 Secondi"` → "60 Secondi" renders in accentcolor	<vd-hero title="Da Idea ad App in 60 Secondi" subtitle="Descrivi la tua app..." eyebrow="🇮🇹 Made in Italy" imgsrc="preview.jpg" accentcolor="#667eea"> <vd-chip slot="badges" icon="♾️" label="Token Illimitati"></vd-chip> <vd-button slot="cta" label="Inizia Gratis" href="register.php"></vd-button> </vd-hero>
<vd-section>	title — section heading (renders as <h2>) subtitle — introductory paragraph below heading backgroundcolor — section background textcolor — text color maxwidth — inner content max-width (default: 1100px) padding — inner padding (default: 80px 2rem) align — text-align: `left` \| `center` \| `right`	Semantic section wrapper with built-in heading, subtitle, max-width centering, and slot for any content. Replaces the repeated `<div class="page-section">` boilerplate on multi-section pages. Uses a real `<section>` element with `aria-label` for accessibility.	<vd-section title="Caratteristiche" subtitle="Una suite completa..." textcolor="#fff" backgroundcolor="#0d0d1a"> <vd-colorcard ...>...</vd-colorcard> </vd-section>
<vd-pricingcard>	title — plan name price — numeric price (e.g. "4.99") currency — currency symbol (default: "€") period — billing period label (default: "/mo") note — small note below price (e.g. "+ API cost") description — plan summary paragraph backgroundcolor, textcolor, shadowcolor accentcolor — CTA and featured border color featured — boolean; shows featured badge + accent border featuredlabel — featured badge text (default: "⭐ Most Popular") ctalabel — CTA button text (default: "Get Started") ctahref — CTA link URL ctatarget — CTA link target (default: _self)	Dedicated pricing card with price display, feature checklist slot, and CTA button. Slot items (`<li>`) render as a feature checklist — style them yourself or prefix with emojis/checkmarks. Events fired: `vd-cta-click` — `{element, href, label}` — on CTA click (bubbles, composed)	<vd-pricingcard title="Beta" price="4.99" currency="€" period="/mese" note="+ OpenAI API a consumo" featured featuredlabel="🚀 Early Access" ctalabel="Inizia Gratis" ctahref="register.php" accentcolor="#667eea"> <li>♾️ Token illimitati</li> <li>🐙 GitHub push nativo</li> </vd-pricingcard>

All new Phase 6 components extend VDBaseElement, use Shadow DOM, fire custom events with bubbles:true, composed:true, and are keyboard-accessible.

🔧 VDBaseElement API (v4)

Method	Description
_addListener(target, event, fn, [opts])	Register event listener — auto-removed on disconnect
_addInterval(fn, delay)	Register interval — auto-cleared on disconnect
_addTimeout(fn, delay)	Register timeout — auto-cleared on disconnect
_makeAccessible(el, {label, role, keyAction})	Add ARIA role, aria-label, tabindex and keyboard handler
static get shadowMode()	Return `"none"` to skip Shadow DOM (light DOM mode)
disconnectedCallback()	Auto-cleanup — override with `super.disconnectedCallback()`

🔐 Security: OpenAI Proxy (v4)

v4 replaces the key.ini client-side fetch with a server-side openai_proxy.php.
The browser only calls openai_proxy.php — the API key is never exposed in DevTools.
Set the key via environment variable OPENAI_API_KEY or a .env file outside the webroot.
Never commit API keys to version control.

📚 VD Framework 4 — Complete Reference

⚙️ Required Load Order

📖 Legend

🆕 Phase 6 — New Components

🔧 VDBaseElement API (v4)

🔐 Security: OpenAI Proxy (v4)