@getvitops/generator 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @getvitops/generator
+
+Generate design-system outputs — **Bricks** (WordPress), standalone **CSS**, and **Tailwind
+v4** (Astro/EmDash) — from a single `design-system.json`. This is the library that powers
+[`@getvitops/cli`](https://www.npmjs.com/package/@getvitops/cli) and
+[`@getvitops/vite`](https://www.npmjs.com/package/@getvitops/vite).
+
+```ts
+import { generate, validate, defaultConfig } from '@getvitops/generator';
+
+await generate({
+  input: './design-system.json', // path or a config object
+  format: 'tailwind', // 'bricks' | 'css' | 'tailwind'
+  outDir: './src/styles',
+});
+```
+
+## API
+
+- `generate({ input, format, outDir })` → writes the chosen format into `outDir`.
+- `validate(configOrObject)` → `{ ok, errors }` against the schema.
+- `defaultConfig()` → a complete starter `DesignSystem`.
+- `DesignSystemSchema` / `jsonSchema` / `SCHEMA_URL` — the `zod/mini` schema, its JSON Schema,
+  and the published schema URL. The schema is the single source of truth (types + validation +
+  JSON Schema all derive from it). The JSON Schema ships as `@getvitops/generator/schema.json`.
+
+## Output per format
+
+| format     | writes                                                                                                   |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| `tailwind` | `tailwind.css` (self-contained, `@import "tailwindcss"`) + `tokens.json`                                 |
+| `css`      | `styles.css` (bundled, standalone) + `tokens.json` + `design-manifest.json`                              |
+| `bricks`   | `styles.min.css`, `bricks-colors-*.json`, `bricks-variables.json`, `tokens.json`, JS, `bricks/`, `docs/` |
+
+See the [`design-system.json` schema](./schema.json) for the config shape.

package/assets/bricks/elements/carousel.php

@@ -0,0 +1,89 @@
+<?php
+/**
+ * Vitops — Carousel element (Bricks Builder).
+ *
+ * Renders the <wc-carousel> Lit component (src/web-components/WCCarousel.ts): an
+ * infinite-loop carousel that progressively enhances the CSS-only `.carousel`. Each
+ * direct child is a slide. Without JS the `.carousel` classes still yield a working
+ * (non-looping) scroll-snap carousel, so the builder canvas stays functional.
+ *
+ * The `.carousel` base rides on the built-in "CSS classes" setting (defaulted below) so
+ * it applies in the canvas and the frontend. Add modifier classes there:
+ * `carousel--scroll-buttons`, `carousel--scroll-markers`, `carousel--auto-pages`.
+ *
+ * Owned by the framework repo (vitops: bricks/elements/); copied into the theme's
+ * dist/bricks/ on build — do not hand-edit in the theme.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+class Vitops_Element_Carousel extends \Bricks\Element {
+	public $category      = 'vitops';
+	public $name          = 'vitops-carousel';
+	public $icon          = 'ti-layout-slider-alt';
+	public $css_selector  = 'wc-carousel';
+	public $nestable      = true;
+	public $vue_component = 'bricks-nestable';
+
+	public function get_label() {
+		return esc_html__( 'Carousel', 'bricks' );
+	}
+
+	public function get_keywords() {
+		return array( 'carousel', 'slider', 'slides', 'gallery', 'scroll', 'vitops' );
+	}
+
+	public function set_controls() {
+		$this->controls['autoplay'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Autoplay interval (ms)', 'bricks' ),
+			'type'        => 'number',
+			'placeholder' => '0',
+			'description' => esc_html__( 'Milliseconds between slides. Leave empty / 0 to disable.', 'bricks' ),
+		);
+
+		$this->controls['label'] = array(
+			'tab'   => 'content',
+			'label' => esc_html__( 'Accessible label (aria-label)', 'bricks' ),
+			'type'  => 'text',
+		);
+
+		$this->controls['modifiersInfo'] = array(
+			'tab'     => 'content',
+			'type'    => 'info',
+			'content' => esc_html__( 'Add modifier classes in "CSS classes": carousel--scroll-buttons, carousel--scroll-markers, carousel--auto-pages. Each direct child is a slide.', 'bricks' ),
+		);
+
+		// Base carousel class defaulted onto the built-in "CSS classes" setting.
+		$this->controls['_cssClasses']['default'] = 'carousel';
+	}
+
+	// Seed three empty slides — the author fills each.
+	public function get_nestable_children() {
+		return array(
+			array( 'name' => 'block', 'label' => esc_html__( 'Slide 1', 'bricks' ) ),
+			array( 'name' => 'block', 'label' => esc_html__( 'Slide 2', 'bricks' ) ),
+			array( 'name' => 'block', 'label' => esc_html__( 'Slide 3', 'bricks' ) ),
+		);
+	}
+
+	public function render() {
+		$s     = $this->settings;
+		$attrs = array();
+
+		if ( isset( $s['autoplay'] ) && '' !== $s['autoplay'] && (int) $s['autoplay'] > 0 ) {
+			$attrs[] = 'autoplay="' . esc_attr( $s['autoplay'] ) . '"';
+		}
+		if ( ! empty( $s['label'] ) ) {
+			$attrs[] = 'aria-label="' . esc_attr( $s['label'] ) . '"';
+		}
+
+		$attr_str = implode( ' ', $attrs );
+
+		echo "<wc-carousel {$attr_str} {$this->render_attributes( '_root' )}>";
+		echo \Bricks\Frontend::render_children( $this );
+		echo '</wc-carousel>';
+	}
+}

package/assets/bricks/elements/centered.php

@@ -0,0 +1,128 @@
+<?php
+/**
+ * Vitops — Centered layout element (Bricks Builder).
+ *
+ * A nestable container that renders the framework's named-track grid, `.centered`
+ * (src/css/layout.css). Children auto-place in the reading `measure` track; a child
+ * widens by adding `breakout` / `spotlight` / `fullbleed` (+ responsive `-sm/-md/-lg/-xl`)
+ * in its own Bricks "CSS classes" field.
+ *
+ * The framework classes ride on the built-in "CSS classes" setting (defaulted below):
+ * a nestable element's root is assembled from settings in the builder canvas, so classes
+ * added only in render()/set_root_attributes() never appear there — _cssClasses does.
+ *
+ * Owned by the framework repo (vitops: bricks/elements/); copied into the theme's
+ * dist/bricks/ on build — do not hand-edit in the theme.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+class Vitops_Element_Centered extends \Bricks\Element {
+	public $category      = 'vitops';
+	public $name          = 'vitops-centered';
+	public $icon          = 'ti-layout-width-default';
+	public $css_selector  = '.centered';
+	public $nestable      = true;
+	public $vue_component = 'bricks-nestable';
+
+	public function get_label() {
+		return esc_html__( 'Centered', 'bricks' );
+	}
+
+	public function get_keywords() {
+		return [ 'centered', 'measure', 'grid', 'container', 'layout', 'track', 'vitops' ];
+	}
+
+	public function set_control_groups() {
+		$this->control_groups['tracks'] = [
+			'title' => esc_html__( 'Track widths', 'bricks' ),
+			'tab'   => 'content',
+		];
+	}
+
+	public function set_controls() {
+		$this->controls['tag'] = [
+			'tab'       => 'content',
+			'label'     => esc_html__( 'HTML tag', 'bricks' ),
+			'type'      => 'select',
+			'inline'    => true,
+			'options'   => [
+				'div'     => 'div',
+				'section' => 'section',
+				'article' => 'article',
+				'aside'   => 'aside',
+				'main'    => 'main',
+				'header'  => 'header',
+				'footer'  => 'footer',
+				'nav'     => 'nav',
+			],
+			'default'   => 'div',
+			'lowercase' => true,
+		];
+
+		// Each width control writes a CSS custom property onto the element root
+		// (.centered), where the grid template reads it. Defaults mirror layout.css.
+		$this->controls['measure'] = [
+			'tab'     => 'content',
+			'group'   => 'tracks',
+			'label'   => esc_html__( 'Measure (reading width)', 'bricks' ),
+			'type'    => 'number',
+			'units'   => true,
+			'default' => '65ch',
+			'css'     => [ [ 'property' => '--width-measure', 'selector' => '' ] ],
+		];
+
+		$this->controls['breakout'] = [
+			'tab'     => 'content',
+			'group'   => 'tracks',
+			'label'   => esc_html__( 'Breakout width', 'bricks' ),
+			'type'    => 'number',
+			'units'   => true,
+			'default' => '90ch',
+			'css'     => [ [ 'property' => '--width-breakout', 'selector' => '' ] ],
+		];
+
+		$this->controls['spotlight'] = [
+			'tab'     => 'content',
+			'group'   => 'tracks',
+			'label'   => esc_html__( 'Spotlight width', 'bricks' ),
+			'type'    => 'number',
+			'units'   => true,
+			'default' => '120ch',
+			'css'     => [ [ 'property' => '--width-spotlight', 'selector' => '' ] ],
+		];
+
+		// Gutter is a `text` control so it accepts the framework default clamp().
+		$this->controls['gutter'] = [
+			'tab'         => 'content',
+			'group'       => 'tracks',
+			'label'       => esc_html__( 'Gutter', 'bricks' ),
+			'type'        => 'text',
+			'placeholder' => 'clamp(1rem, 4cqi, 3rem)',
+			'css'         => [ [ 'property' => '--gutter', 'selector' => '' ] ],
+		];
+
+		// Framework classes default onto the built-in "CSS classes" setting so they
+		// apply in the builder canvas AND the frontend. `rhythm` (relationship-based
+		// vertical spacing) is on by default — remove it in the CSS-classes field to
+		// disable. (It's a class, not a checkbox, because a nestable element can't
+		// reflect a PHP-computed root class in the builder.)
+		$this->controls['_cssClasses']['default'] = 'centered rhythm';
+	}
+
+	// No seeded children: a Centered container starts empty. Each direct child is
+	// auto-placed in the reading `measure` track; the author widens one by adding
+	// `breakout` / `spotlight` / `fullbleed` (+ `-sm/-md/-lg/-xl`) in its own
+	// Bricks "CSS classes" field — no wrapper or preset child needed.
+
+	public function render() {
+		// $this->tag is resolved from the `tag` setting by the base (get_tag()).
+		// render_children() returns child HTML on the frontend and the nestable
+		// drag-drop placeholder inside the builder.
+		echo "<{$this->tag} {$this->render_attributes( '_root' )}>";
+		echo \Bricks\Frontend::render_children( $this );
+		echo "</{$this->tag}>";
+	}
+}

package/assets/bricks/elements/color-scheme-toggle.php

@@ -0,0 +1,61 @@
+<?php
+/**
+ * Vitops — Color Scheme Toggle element (Bricks Builder).
+ *
+ * Renders the <color-scheme-toggle> Lit component (src/web-components/WCColorSchemeToggle.ts):
+ * a segmented System / Light / Dark theme toggle, hidden until JS loads. Optionally seed
+ * the initial `scheme`.
+ *
+ * Non-nestable: PHP render() runs in the builder canvas too, so the toggle upgrades
+ * live while editing.
+ *
+ * Owned by the framework repo (vitops: bricks/elements/); copied into the theme's
+ * dist/bricks/ on build — do not hand-edit in the theme.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+class Vitops_Element_Color_Scheme_Toggle extends \Bricks\Element {
+	public $category     = 'vitops';
+	public $name         = 'vitops-color-scheme-toggle';
+	public $icon         = 'ti-shine';
+	public $css_selector = 'color-scheme-toggle';
+
+	public function get_label() {
+		return esc_html__( 'Color Scheme Toggle', 'bricks' );
+	}
+
+	public function get_keywords() {
+		return array( 'color', 'scheme', 'theme', 'dark', 'light', 'toggle', 'vitops' );
+	}
+
+	public function set_controls() {
+		$this->controls['scheme'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Initial scheme', 'bricks' ),
+			'type'        => 'select',
+			'inline'      => true,
+			'options'     => array(
+				'system' => esc_html__( 'System', 'bricks' ),
+				'light'  => esc_html__( 'Light', 'bricks' ),
+				'dark'   => esc_html__( 'Dark', 'bricks' ),
+			),
+			'placeholder' => esc_html__( 'System', 'bricks' ),
+		);
+	}
+
+	public function render() {
+		$s     = $this->settings;
+		$attrs = array();
+
+		if ( ! empty( $s['scheme'] ) ) {
+			$attrs[] = 'scheme="' . esc_attr( $s['scheme'] ) . '"';
+		}
+
+		$attr_str = implode( ' ', $attrs );
+
+		echo "<color-scheme-toggle {$attr_str} {$this->render_attributes( '_root' )}></color-scheme-toggle>";
+	}
+}

package/assets/bricks/elements/copy-button.php

@@ -0,0 +1,65 @@
+<?php
+/**
+ * Vitops — Copy Button element (Bricks Builder).
+ *
+ * Renders the <copy-button> Lit component (src/web-components/WCCopy.ts): a
+ * copy-to-clipboard button, hidden until connected (Clipboard API gate). The `value`
+ * is copied; `label` is the button text (falls back to slotted text).
+ *
+ * Non-nestable: PHP render() runs in the builder canvas too, so the button upgrades
+ * live while editing.
+ *
+ * Owned by the framework repo (vitops: bricks/elements/); copied into the theme's
+ * dist/bricks/ on build — do not hand-edit in the theme.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+class Vitops_Element_Copy extends \Bricks\Element {
+	public $category     = 'vitops';
+	public $name         = 'vitops-copy-button';
+	public $icon         = 'ti-clipboard';
+	public $css_selector = 'copy-button';
+
+	public function get_label() {
+		return esc_html__( 'Copy Button', 'bricks' );
+	}
+
+	public function get_keywords() {
+		return array( 'copy', 'clipboard', 'button', 'vitops' );
+	}
+
+	public function set_controls() {
+		$this->controls['value'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Value to copy', 'bricks' ),
+			'type'        => 'text',
+		);
+
+		$this->controls['label'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Button label', 'bricks' ),
+			'type'        => 'text',
+			'placeholder' => esc_html__( 'Copy to clipboard', 'bricks' ),
+		);
+	}
+
+	public function render() {
+		$s     = $this->settings;
+		$attrs = array();
+
+		if ( isset( $s['value'] ) && '' !== $s['value'] ) {
+			$attrs[] = 'value="' . esc_attr( $s['value'] ) . '"';
+		}
+		if ( ! empty( $s['label'] ) ) {
+			$attrs[] = 'label="' . esc_attr( $s['label'] ) . '"';
+		}
+
+		$attr_str = implode( ' ', $attrs );
+		$fallback = ! empty( $s['label'] ) ? esc_html( $s['label'] ) : esc_html__( 'Copy to clipboard', 'bricks' );
+
+		echo "<copy-button {$attr_str} {$this->render_attributes( '_root' )}>{$fallback}</copy-button>";
+	}
+}

package/assets/bricks/elements/dismissable.php

@@ -0,0 +1,93 @@
+<?php
+/**
+ * Vitops — Dismissable element (Bricks Builder).
+ *
+ * Renders the <wc-dismissable> Lit component (src/web-components/WCDismissable.ts): a
+ * light-DOM progressive-enhancement wrapper. A click on any descendant marked
+ * `data-dismiss` (e.g. the seeded close button) fades the wrapper out and removes it.
+ * Optional `duration` auto-dismisses after N ms; `exit` sets the fade time.
+ *
+ * Without JS the wrapper is an inert unknown tag and its content still renders, so the
+ * builder canvas stays functional.
+ *
+ * Owned by the framework repo (vitops: bricks/elements/); copied into the theme's
+ * dist/bricks/ on build — do not hand-edit in the theme.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+class Vitops_Element_Dismissable extends \Bricks\Element {
+	public $category      = 'vitops';
+	public $name          = 'vitops-dismissable';
+	public $icon          = 'ti-close';
+	public $css_selector  = 'wc-dismissable';
+	public $nestable      = true;
+	public $vue_component = 'bricks-nestable';
+
+	public function get_label() {
+		return esc_html__( 'Dismissable', 'bricks' );
+	}
+
+	public function get_keywords() {
+		return array( 'dismiss', 'close', 'banner', 'notice', 'alert', 'vitops' );
+	}
+
+	public function set_controls() {
+		$this->controls['duration'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Auto-dismiss after (ms)', 'bricks' ),
+			'type'        => 'number',
+			'description' => esc_html__( 'Leave empty to require a click on a [data-dismiss] element.', 'bricks' ),
+		);
+
+		$this->controls['exit'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Fade-out time (ms)', 'bricks' ),
+			'type'        => 'number',
+		);
+
+		$this->controls['dismissInfo'] = array(
+			'tab'     => 'content',
+			'type'    => 'info',
+			'content' => esc_html__( 'Any child with a data-dismiss attribute acts as a close trigger. The seeded button already has it.', 'bricks' ),
+		);
+	}
+
+	// Seed content + a close button carrying data-dismiss.
+	public function get_nestable_children() {
+		return array(
+			array( 'name' => 'block', 'label' => esc_html__( 'Content', 'bricks' ) ),
+			array(
+				'name'     => 'text-basic',
+				'label'    => esc_html__( 'Close (×)', 'bricks' ),
+				'settings' => array(
+					'text'        => '&times;',
+					'_attributes' => array(
+						array( 'id' => 'vdismiss', 'name' => 'data-dismiss', 'value' => '' ),
+						array( 'id' => 'vdismisslbl', 'name' => 'aria-label', 'value' => 'Dismiss' ),
+					),
+				),
+			),
+		);
+	}
+
+	public function render() {
+		$s     = $this->settings;
+		$attrs = array();
+
+		if ( isset( $s['duration'] ) && '' !== $s['duration'] ) {
+			$attrs[] = 'duration="' . esc_attr( $s['duration'] ) . '"';
+		}
+		if ( isset( $s['exit'] ) && '' !== $s['exit'] ) {
+			$attrs[] = 'exit="' . esc_attr( $s['exit'] ) . '"';
+		}
+
+		$attr_str = implode( ' ', $attrs );
+
+		echo "<wc-dismissable {$attr_str} {$this->render_attributes( '_root' )}>";
+		echo \Bricks\Frontend::render_children( $this );
+		echo '</wc-dismissable>';
+	}
+}

package/assets/bricks/elements/entries.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * Vitops — Entries element (Bricks Builder).
+ *
+ * Renders the <wc-entries> Lit component (src/web-components/WCEntries.ts): an adaptive
+ * data display that enhances a series of heading + <dl> pairs into a table / column
+ * projection based on container width. Without JS the heading + <dl> pairs render
+ * stacked (semantic), so the builder canvas stays functional.
+ *
+ * Slotted content structure (add via Code / HTML children):
+ *   <h3>Group title</h3>
+ *   <dl><dt>Label</dt><dd>Value</dd> …</dl>
+ *   (repeat)
+ *
+ * Owned by the framework repo (vitops: bricks/elements/); copied into the theme's
+ * dist/bricks/ on build — do not hand-edit in the theme.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+class Vitops_Element_Entries extends \Bricks\Element {
+	public $category      = 'vitops';
+	public $name          = 'vitops-entries';
+	public $icon          = 'ti-layout-list-thumb';
+	public $css_selector  = 'wc-entries';
+	public $nestable      = true;
+	public $vue_component = 'bricks-nestable';
+
+	public function get_label() {
+		return esc_html__( 'Entries', 'bricks' );
+	}
+
+	public function get_keywords() {
+		return array( 'entries', 'data', 'table', 'definition', 'list', 'dl', 'vitops' );
+	}
+
+	public function set_controls() {
+		$this->controls['breakpoint'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Breakpoint', 'bricks' ),
+			'type'        => 'text',
+			'placeholder' => '40rem',
+			'description' => esc_html__( 'Container width below which the projected/table view engages.', 'bricks' ),
+		);
+
+		$this->controls['projection'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Column projection (table)', 'bricks' ),
+			'type'        => 'checkbox',
+			'description' => esc_html__( 'Project heading + <dl> pairs into a table.', 'bricks' ),
+		);
+
+		$this->controls['singular'] = array(
+			'tab'         => 'content',
+			'label'       => esc_html__( 'Singular (one row at a time)', 'bricks' ),
+			'type'        => 'checkbox',
+			'description' => esc_html__( 'With projection + narrow: show one row with nav.', 'bricks' ),
+		);
+
+		$this->controls['structureInfo'] = array(
+			'tab'     => 'content',
+			'type'    => 'info',
+			'content' => esc_html__( 'Add children as heading + <dl> pairs: an <h3> group title followed by a <dl> of <dt>Label</dt><dd>Value</dd> pairs. Use a Code / HTML element for the <dl>.', 'bricks' ),
+		);
+	}
+
+	// Seed a heading so the structure is discoverable; the author adds the <dl>.
+	public function get_nestable_children() {
+		return array(
+			array( 'name' => 'heading', 'label' => esc_html__( 'Group title', 'bricks' ) ),
+		);
+	}
+
+	public function render() {
+		$s     = $this->settings;
+		$attrs = array();
+
+		if ( ! empty( $s['breakpoint'] ) ) {
+			$attrs[] = 'breakpoint="' . esc_attr( $s['breakpoint'] ) . '"';
+		}
+		if ( ! empty( $s['projection'] ) ) {
+			$attrs[] = 'projection';
+		}
+		if ( ! empty( $s['singular'] ) ) {
+			$attrs[] = 'singular';
+		}
+
+		$attr_str = implode( ' ', $attrs );
+
+		echo "<wc-entries {$attr_str} {$this->render_attributes( '_root' )}>";
+		echo \Bricks\Frontend::render_children( $this );
+		echo '</wc-entries>';
+	}
+}