Skip to content
dwrthPublic

About

Controlled grid layout builder for React. Drag, resize, restack, and compose sections on a responsive CSS grid.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Vantage

Controlled grid layout builder for React. Drag, resize, restack, and compose sections on a responsive CSS grid. You bring every block component; Vantage handles layout chrome, breakpoints, and the data model.

Demo under demo/ — toolbar, layers, inspectors, context menu, persistence, seven block kinds:

cd demo && npm install && npm run dev

Install

npm i @dwrth/vantage

Requires react and react-dom 18 or 19.

Quick start

import { useState } from 'react';
import {
  VantageBuilder,
  VantagePreview,
  createEmptyLayout,
  defineKind,
  type Layout,
  type PreviewRendererProps,
  type EditRendererProps,
} from '@dwrth/vantage';
import '@dwrth/vantage/style.css';

type HeroData = { title: string; body: string };

function HeroPreview({ item }: PreviewRendererProps<HeroData>) {
  return (
    <div>
      <h2>{item.data?.title}</h2>
      <p>{item.data?.body}</p>
    </div>
  );
}

function HeroEdit({ item }: EditRendererProps<HeroData>) {
  return (
    <div>
      <h2>{item.data?.title}</h2>
      <p>{item.data?.body}</p>
      <span>Editing</span>
    </div>
  );
}

const heroKind = defineKind<HeroData>({
  component: HeroPreview,
  editComponent: HeroEdit,
  defaults: { w: 6, h: 4, label: 'Hero', data: { title: 'Hello', body: 'World' } },
  displayName: 'Hero',
});

const components = { hero: heroKind };

function App() {
  const [layout, setLayout] = useState<Layout>(createEmptyLayout);
  return (
    <>
      <VantageBuilder value={layout} onChange={(next) => setLayout(next)} components={components} />
      <VantagePreview value={layout} components={components} />
    </>
  );
}

Breakpoints, overrides, layers, persistence — all opt-in. Default: single-section desktop builder via createEmptyLayout().

On published pages pass emptyState={null} to VantagePreview so a layout without sections renders nothing instead of the "Nothing to preview yet." hint, or pass a localized node to replace the text (details).

Docs

Topic
Components VantageBuilder, VantagePreview, defineKind
Layout model & mutations Data shape, sections, items, layering, import/export
Breakpoints Responsive overrides, resolution helpers
Arrangement Preset flow sections, drop preview, breakpoints
Alignment Guides, content alignment
Content minimum size getItemMinSize, resize floor
Selection Controlled / uncontrolled selection
Section backgrounds Color, image, blur, focal crop, parallax
Persistence ref, strip/hydrate, kind persist hooks, file I/O
Undo / history useVantageHistory, gesture merging, reset
Keyboard & a11y Shortcuts, focus, reading order, announcements
Custom blocks defineKind patterns, interactivity, pitfalls
Theme / tokens VantageThemeProvider, opaque CSS token maps
Host panels VantageInspector, layers, toolbars (demo patterns)

Development

# library
npm install
npm run build      # dist/
npm run typecheck

# demo
cd demo
npm install
npm run dev        # http://localhost:5173

Releasing

Releases go to npm from GitHub Actions (.github/workflows/release.yml, trusted publishing with provenance; no npm token).

  1. Bump version in package.json and package-lock.json (npm version X.Y.Z --no-git-tag-version) in a PR.
  2. Merge it into main.
  3. Create a GitHub release with the tag vX.Y.Z on main. Publishing it runs the workflow, which fails if the tag does not match package.json, then typechecks, tests, builds and publishes.

About

Controlled grid layout builder for React. Drag, resize, restack, and compose sections on a responsive CSS grid.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages