VastUI

VastUI is Vastare's shared tree-shakable SCSS and TypeScript UI kit.

It provides reusable public, admin, and framework-adaptable component foundations for WordPress themes, raw JavaScript/TypeScript frontends, and future SPA adapters.

VastUI sits above Fundatio. Fundatio owns design tokens, typography foundations, semantic defaults, CSS contracts, accessibility primitives, and Bootstrap adapter foundations. VastUI consumes those foundations and provides reusable UI component structure, styles, behaviours, and adapter patterns.

Package identity

Repository: pkgn-vastui
Package: @vastare/pkgn-vastui
Public name: VastUI
Current version: 0.7.0

v0.7.0 scope

This version keeps the working public Main Navbar from v0.6.0 and adds default profile identity values for the profile trigger and dropdown card. Consumers may override the profile image source, image alt text, display name, and subtitle, while the v0.6.0 profile menu item contract remains fixed.

The component still preserves the .vastare-site-navigation selector contract, Bootstrap-first markup, Fundatio-first styling, static demo support, and existing dropdown/collapse behaviour. It extends typed config resolution and DOM render helpers for profile identity display without forcing consumers to use generated markup. WordPress themes and other server-rendered consumers can still provide their own markup and use VastUI only for styles/behaviour.

It does not add real user loading, email handling, auth/session state, VastID API calls, avatar upload/cropping, permission-based menu items, WordPress PHP, Vue, React, BFF logout integration, or automatic DOM initialisation.

Component layers

VastUI uses core, not global, for shared reusable components. global sounds like global styles, root styles, and side effects, which is exactly the swamp this package is avoiding.

core     Shared reusable primitives and neutral components.
public   Customer-facing/front-end/marketing/content components.
admin    Internal/admin/operational components.
adapters Raw, WordPress, Vue, React, or future platform wrappers.
demo     Local package demo site that consumes VastUI like a user would.

Shared components used by both public and admin consumers belong in core unless they carry public-only or admin-only assumptions.

Relationship to Fundatio

Fundatio owns the foundation:

• design tokens
• colour system
• typography foundations
• semantic defaults
• CSS contracts
• SCSS maps/functions/mixins
• accessibility primitives
• Bootstrap Adapter/Core
• base/root/page setup

VastUI owns reusable components and component-level behaviour. If a concern belongs to Fundatio, do not duplicate it here. If a concern belongs to an app, theme, plugin, or demo page, do not force it into VastUI.

Styling priority

Every component must follow this order:

1. Use Fundatio tokens, contracts, utilities, classes, mixins, functions, and CSS custom properties first.
2. Use Fundatio's Bootstrap Adapter/Core when Bootstrap-compatible structure is needed.
3. Use Bootstrap classes/components/dependencies when Bootstrap already solves the structure or behaviour.
4. Use VastUI SCSS only for the remaining component-specific refinement.
5. Write raw CSS only if absolutely unavoidable.

Do not recreate Bootstrap components such as .navbar, .dropdown, .collapse, .nav, .btn, .card, .alert, or .badge under new VastUI-only structures. Use Bootstrap's class contract and extend it.

JavaScript and TypeScript usage

VastUI source is written in TypeScript and distributed as JavaScript with TypeScript declaration files.

JavaScript consumers can import the generated JavaScript:

import { createVastUiId } from '@vastare/pkgn-vastui/core';

TypeScript consumers use the same import paths and receive declarations:

import { getFocusableElements } from '@vastare/pkgn-vastui/core';

CSS and SCSS usage

VastUI source styles are written in SCSS and compiled to CSS.

SCSS consumers can import modular source entry points:

@use '@vastare/pkgn-vastui/scss/core';
@use '@vastare/pkgn-vastui/scss/public';
@use '@vastare/pkgn-vastui/scss/admin';

CSS consumers can import compiled CSS entry points after the package has been built:

import '@vastare/pkgn-vastui/css/core';
import '@vastare/pkgn-vastui/css/public';
import '@vastare/pkgn-vastui/css/admin';

Future component-specific imports should look like this:

import { Button } from '@vastare/pkgn-vastui/core/button';

@use '@vastare/pkgn-vastui/scss/core/button';

import '@vastare/pkgn-vastui/css/core/button.css';

Tree-shaking rules

Every future component must be individually tree-shakable.

Hard rules:

• one component, one TypeScript entry point
• one component, one SCSS entry point when styles are needed
• one component, one compiled CSS entry point when CSS output is produced
• component TypeScript must not import SCSS by default
• grouped exports must stay side-effect free
• root export must stay tiny
• public and admin components must not cross-import each other
• adapters must not leak framework dependencies into core consumers

Demo page

The root demo/ folder is a local consumer-style demo site. It uses demo-owned page styles and consumes foundation styles like an app, while real VastUI components remain tree-shakable package exports that both the demo and external consumers can import later.

demo/
├─ index.html
├─ main.ts
├─ css/
│  ├─ demo.css              Generated from demo SCSS. Do not edit directly.
│  └─ main-navbar.css       Generated from component SCSS. Do not edit directly.
├─ fonts/                   Generated from Fundatio. Do not edit directly.
├─ js/
│  └─ demo.js               Generated from TypeScript. Do not edit directly.
└─ scss/
   ├─ demo.scss
   ├─ foundation/
   │  ├─ _fundatio.scss
   │  └─ _bootstrap-components.scss
   └─ demo/
      ├─ _layout.scss
      └─ _content.scss

The demo links compiled demo CSS from demo/index.html, while the stylesheet is generated from SCSS source that consumes Fundatio/base styles for page setup. The demo then consumes VastUI like any external app would. Demo-only page layout belongs in demo/scss; reusable component styles belong in src/scss only when real components exist.

Run the demo locally:

npm run dev:demo

Build the demo separately from the package build:

npm run build:demo

The v0.7.0 demo keeps default Main Navbar markup in demo/index.html so the default Vastare logo, single Homepage item, default profile identity, and default profile dropdown items are visible even before JavaScript runs. The demo then calls initialiseVastUiMainNavbar() without consumer config to initialise Bootstrap-backed behaviour without replacing the static defaults. The demo links generated browser-safe CSS and JS only: ./css/demo.css, ./css/main-navbar.css, and ./js/demo.js?v=0.7.0-static-demo. Demo CSS is generated from SCSS, demo JavaScript is generated from TypeScript into one static IIFE browser bundle, and Fundatio fonts are copied into browser-visible demo font paths so the generated @font-face URLs resolve without console 404s.

Documentation

See the docs/ folder for the architecture rules introduced in v0.2.0 and the demo foundation fixed and confirmed through v0.7.0:

• docs/architecture.md
• docs/component-layers.md
• docs/component-taxonomy.md
• docs/component-creation.md
• docs/styling.md
• docs/tree-shaking.md
• docs/exports.md
• docs/accessibility.md
• docs/testing.md
• docs/demo.md
• docs/fundatio-integration.md
• docs/bootstrap-usage.md
• docs/release-validation.md

Development

npm install
npm run typecheck
npm run build
npm run test
npm run pack:dry

Full package check:

npm run check

Demo check:

npm run build:demo

Publication note

The package is currently marked private: true and UNLICENSED to prevent accidental publication before the licensing and publication strategy is confirmed.

Main Navbar

VastUI 0.7.0 includes the public Main Navbar introduced in v0.4.0, configurable logo/brand and primary menu rendering from v0.5.0, default profile menu item support, and default profile identity values. It deliberately preserves the .vastare-site-navigation class contract for visual parity with the wpth-vastare source navbar.

import { initialiseVastUiMainNavbar } from '@vastare/pkgn-vastui/public/main-navbar';

initialiseVastUiMainNavbar({
  config: {
    logo: {
      href: 'https://www.vastare.co.uk',
      alt: 'Vastare',
    },
    primaryMenu: [
      { label: 'Homepage', href: 'https://www.vastare.co.uk', active: true },
      { label: 'Services', href: '/services/' },
    ],
    profileMenu: {
      myAccountHref: 'https://example.com/my-account',
      imageSrc: '/assets/users/example.jpg',
      imageAlt: 'Example User',
      name: 'Example User',
      subtitle: 'Vastare account',
    },
  },
});

@use '@vastare/pkgn-vastui/scss/public/main-navbar';

import '@vastare/pkgn-vastui/css/public/main-navbar.css';

The component includes reusable SCSS and opt-in TypeScript behaviour only. It does not include WordPress PHP, Vue, React, service calls, or automatic DOM initialisation.

Main Navbar configuration

The Main Navbar supports two usage modes:

1. Server-rendered/manual markup: consumers render the existing Bootstrap/Vastare class contract and call initialiseVastUiMainNavbar().
2. Config-generated markup: consumers pass a config object or call the render helpers, then initialise behaviour.

If no logo config is supplied to the render helpers, VastUI uses a default Vastare logo, Vastare alt text, and https://www.vastare.co.uk as the brand URL. If no primary menu is supplied, VastUI renders one Homepage item pointing at https://www.vastare.co.uk. If no profile menu config is supplied, VastUI renders My account, Identity, Security, Connected applications, Appearance, and a POST Log Out action. Consumer-provided labels are rendered as text content, not HTML, and unsafe javascript:, vbscript:, and consumer data: URLs fall back to safe defaults.

The package demo intentionally calls initialiseVastUiMainNavbar() without a consumer config so the default logo, default single Homepage menu, default profile identity, and default profile menu stay visible and testable. Consumer override examples belong in documentation and tests, not as hidden demo defaults.

import {
  applyVastUiMainNavbarConfig,
  initialiseVastUiMainNavbar,
} from '@vastare/pkgn-vastui/public/main-navbar';

applyVastUiMainNavbarConfig({
  config: {
    primaryMenu: [
      { label: 'Homepage', href: 'https://www.vastare.co.uk', active: true },
      {
        label: 'Ventures',
        children: [
          {
            label: 'Apps',
            children: [
              { label: 'LifeAnchor', href: '/ventures/lifeanchor/' },
            ],
          },
        ],
      },
    ],
  },
});

initialiseVastUiMainNavbar();

The profile menu defaults are fixed in v0.6.0: My account, Identity, Security, Connected applications, Appearance, and Log Out. Only profileMenu.myAccountHref can be overridden. The VastID links and POST logout action are intentionally fixed for now, because a dropdown is not a tiny CMS wearing a button costume.

Main Navbar JavaScript note

The Main Navbar imports Bootstrap Collapse and Dropdown selectively, then marks only the matching .vastare-site-navigation controls. A scoped capture-phase click bridge runs before Bootstrap’s document-level Data API for those marked controls, so the component gets one Bootstrap-powered toggle instead of either no demo behaviour or a duplicate toggle. Bootstrap still owns the actual Collapse/Dropdown state; VastUI only scopes the wiring for this copied navbar pattern.

Profile identity defaults are:

Profile image/icon: current VS avatar style
Profile name: John Doe
Profile subtitle: Vastare account

Consumers can override these through profileMenu without turning VastUI into an auth store:

initialiseVastUiMainNavbar({
  config: {
    profileMenu: {
      imageSrc: '/assets/users/example.jpg',
      imageAlt: 'Example User',
      name: 'Example User',
      subtitle: 'Vastare account',
    },
  },
});

Only the My account URL remains overrideable among the profile menu item links. The fixed VastID Identity, Security, Connected applications, Appearance, and POST Log Out targets remain unchanged.