@getvitops/core 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @getvitops/core
+
+The Vitops design-system **framework** — the platform-agnostic primitives that the generator
+turns into platform output and that `@getvitops/bricks` / `@getvitops/astro` build on:
+
+- **CSS partials** — the variable-driven framework (layout, utilities, component patterns).
+  Inert on their own; they resolve against the token layer emitted by
+  [`@getvitops/generator`](https://www.npmjs.com/package/@getvitops/generator).
+- **Lit web components** — progressively-enhanced custom elements (`<wc-*>`), self-registering.
+- **Browser polyfills** — a feature-detected loader (Anchor Positioning, Popover, Scroll
+  Timeline, …) used by both the CSS patterns and the web components.
+
+## Subpath exports
+
+```ts
+import '@getvitops/core/polyfills'; // feature-detected polyfill loader (load high in <head>)
+import '@getvitops/core/elements'; // register the Lit web components
+import '@getvitops/core/deferred'; // late progressive-enhancement behaviour
+```
+
+```css
+@import '@getvitops/core/css/index.css'; /* framework partials (needs generated tokens) */
+```
+
+Most consumers don't import the CSS directly — they run
+[`@getvitops/generator`](https://www.npmjs.com/package/@getvitops/generator) (via the
+[CLI](https://www.npmjs.com/package/@getvitops/cli) or
+[Vite plugin](https://www.npmjs.com/package/@getvitops/vite)) to emit a bundled stylesheet
+from their `design-system.json`, and load these JS bundles for interactivity.

package/css/animation.css

@@ -0,0 +1,526 @@
+/**
+ * Animation System — three orthogonal layers
+ *
+ * This file is the ENGINE (keyframes, drivers, floats, utilities), hand-written.
+ * The effect + journey classes are GENERATED from design-system.json `animations`
+ * into ./generated/animation-effects.css (imported right after this file).
+ *
+ *   Effects (the WHAT): set only `--_anim` (which keyframe) +
+ *     `--<prop>-from/-to` vars. Inert alone — a driver supplies the mechanism.
+ *   Drivers (the HOW/WHEN): pair an effect with a mechanism —
+ *     · animate-view / animate-scroll — keyframe linked to a scroll timeline
+ *     · animate-trigger              — keyframe, time-based; plays once when
+ *                                      .is-active / [data-active] is set
+ *     · transition-active / -hover   — TRANSITION (not keyframe) over the same
+ *                                      from/to vars, so it reverses on state flip
+ *   Both driver families read the same `--<prop>-*` vars, so one effect
+ *   (e.g. .fade-in) works in every mode with no redefinition.
+ *
+ * Effects by rendering stage (cheapest → most expensive):
+ *   composite: fade-in/out, slide-up/down/left/right, scale-up/down, rotate-cw/ccw
+ *   paint:     blur-in/out, elevate-up/down, reveal-left/right/up/down
+ *   layout:    size-grow, size-shrink            (keyframe-only — auto height)
+ *   journey:   fade-journey, slide-journey, …    (multi-phase; view timeline)
+ * One keyframe per element: same-stage effects compose via vars (fade-in +
+ * scale-up); cross-stage (fade + blur) needs nested elements.
+ *
+ * Float (continuous, self-contained — no driver): add `.float` + a preset,
+ *   e.g. <div class="float float-circular" style="--float-radius:15px">.
+ *   Path variants use `.float-path` (offset-path).
+ *
+ * Usage:
+ *   <div class="fade-in slide-up animate-view">     <!-- scroll-into-view -->
+ *   <div class="fade-in scale-up animate-trigger">  <!-- play once on enter -->
+ *   <button class="scale-up transition-hover">      <!-- grow on hover -->
+ *   <div class="fade-in slide-up transition-active"><!-- flip via .is-active -->
+ */
+
+/* ===========================================
+ * Configuration
+ * =========================================== */
+
+:root {
+  --custom-ease-in: cubic-bezier(0.33, 1, 0.68, 1);
+  --custom-ease-out: cubic-bezier(0.25, 0.1, 0.25, 1);
+  --animation-duration-fast: 150ms;
+  --animation-duration-base: 250ms;
+  --animation-duration-slow: 500ms;
+  --animation-duration-xslow: 2s;
+  --animation-duration: var(--_animation-duration, var(--animation-duration-slow));
+  --trigger-animation-duration: var(--animation-duration-xslow);
+
+  /* Float easing presets */
+  /* Sinusoidal — smooth continuous speed, natural for 2D orbits */
+  --ease-float-sine: linear(0, 0.024, 0.095, 0.206, 0.354, 0.5, 0.646, 0.794, 0.905, 0.976, 1);
+  /* Soft bounce — decelerates at peaks, good for 1D oscillation */
+  --ease-float-bounce: linear(0, 0.11, 0.36, 0.64, 0.89, 1, 0.89, 0.64, 0.36, 0.11, 0);
+}
+
+/* ===========================================
+ * View Transitions (page navigation)
+ * =========================================== */
+
+@view-transition {
+  navigation: auto;
+}
+
+::view-transition-children(*) {
+  animation-duration: var(--animation-duration-xslow);
+}
+
+/* ===========================================
+ * Keyframes - Layout Stage (most expensive)
+ * =========================================== */
+
+@keyframes layout {
+  from {
+    height: var(--height-from, auto);
+  }
+  to {
+    height: var(--height-to, auto);
+  }
+}
+
+/* ===========================================
+ * Keyframes - Compositor Stage (cheapest, GPU)
+ * opacity + individual transform properties
+ * =========================================== */
+
+@keyframes composite {
+  from {
+    opacity: var(--opacity-from, 1);
+    translate: var(--translate-x-from, 0) var(--translate-y-from, 0);
+    scale: var(--scale-x-from, 1) var(--scale-y-from, 1);
+    rotate: var(--rotate-from, 0deg);
+  }
+  to {
+    opacity: var(--opacity-to, 1);
+    translate: var(--translate-x-to, 0) var(--translate-y-to, 0);
+    scale: var(--scale-x-to, 1) var(--scale-y-to, 1);
+    rotate: var(--rotate-to, 0deg);
+  }
+}
+
+/* ===========================================
+ * Keyframes - Paint Stage
+ * filter functions + clip-path
+ * =========================================== */
+
+@keyframes paint {
+  from {
+    filter: blur(var(--blur-from, 0px)) drop-shadow(var(--shadow-from, 0 0 0 transparent))
+      brightness(var(--brightness-from, 1)) grayscale(var(--grayscale-from, 0))
+      contrast(var(--contrast-from, 1)) saturate(var(--saturate-from, 1))
+      sepia(var(--sepia-from, 0)) hue-rotate(var(--hue-rotate-from, 0deg));
+    clip-path: var(--clip-from, none);
+  }
+  to {
+    filter: blur(var(--blur-to, 0px)) drop-shadow(var(--shadow-to, 0 0 0 transparent))
+      brightness(var(--brightness-to, 1)) grayscale(var(--grayscale-to, 0))
+      contrast(var(--contrast-to, 1)) saturate(var(--saturate-to, 1)) sepia(var(--sepia-to, 0))
+      hue-rotate(var(--hue-rotate-to, 0deg));
+    clip-path: var(--clip-to, none);
+  }
+}
+
+/* ===========================================
+ * Keyframes - Journey (Multi-Phase)
+ * Entry → Hold → Exit pattern
+ * =========================================== */
+
+@keyframes fade-journey {
+  0%,
+  100% {
+    opacity: var(--opacity-from, 0);
+  }
+  25%,
+  75% {
+    opacity: var(--opacity-to, 1);
+  }
+}
+
+@keyframes slide-journey {
+  0% {
+    translate: var(--translate-x-from, 0) var(--translate-y-from, 0);
+  }
+  25%,
+  75% {
+    translate: var(--translate-x-to, 0) var(--translate-y-to, 0);
+  }
+  100% {
+    translate: calc(var(--translate-x-from, 0) * -1) calc(var(--translate-y-from, 0) * -1);
+  }
+}
+
+@keyframes scale-journey {
+  0%,
+  100% {
+    scale: var(--scale-x-from, 0.8) var(--scale-y-from, 0.8);
+  }
+  25%,
+  75% {
+    scale: var(--scale-x-to, 1) var(--scale-y-to, 1);
+  }
+}
+
+@keyframes blur-journey {
+  0%,
+  100% {
+    filter: blur(var(--blur-from, 5px));
+  }
+  25%,
+  75% {
+    filter: blur(var(--blur-to, 0));
+  }
+}
+
+/* ===========================================
+ * Keyframes - Float (Continuous Movement)
+ * 4 configurable waypoints, loops back to start
+ * =========================================== */
+
+@keyframes float {
+  0%,
+  100% {
+    translate: var(--float-x-0, 0) var(--float-y-0, 0);
+  }
+  25% {
+    translate: var(--float-x-25, 0) var(--float-y-25, 0);
+  }
+  50% {
+    translate: var(--float-x-50, 0) var(--float-y-50, 0);
+  }
+  75% {
+    translate: var(--float-x-75, 0) var(--float-y-75, 0);
+  }
+}
+
+@keyframes float-path {
+  from {
+    offset-distance: 0%;
+  }
+  to {
+    offset-distance: 100%;
+  }
+}
+
+/* ===========================================
+ * Keyframes - Utility
+ * =========================================== */
+
+@keyframes bg-position-reveal {
+  from {
+    background-position: var(--bg-position-reveal-from);
+  }
+  to {
+    background-position: var(--bg-position-reveal-to);
+  }
+}
+
+/* ===========================================
+ * Trigger Play-State
+ * Paused until activated. deferred.ts adds .is-active via IntersectionObserver,
+ * but [data-active] / .is-active can also be toggled by any state logic. Gated
+ * on JS (no-js → animation runs immediately, so content is never stuck hidden).
+ * =========================================== */
+
+:where(:root:not(.no-js)) {
+  .animate-trigger {
+    animation-play-state: paused;
+  }
+
+  :is(.is-active, [data-active]).animate-trigger,
+  :is(.is-active, [data-active]) > .animate-trigger {
+    animation-play-state: running;
+  }
+}
+
+/* ===========================================
+ * Float Base — required alongside a preset: class="float float-circular"
+ * (A plain base class beats the old [class*='float-…'] list: extensible, and
+ *  the float-slow/fast/linear modifiers can't accidentally match it.)
+ * =========================================== */
+
+.float {
+  animation-name: float;
+  animation-duration: var(--float-duration, 4s);
+  animation-timing-function: var(--float-easing, ease-in-out);
+  animation-iteration-count: var(--float-iterations, infinite);
+}
+
+/* animation-fill-mode: both — hoisted for every keyframe-driven animation. */
+.animate-view,
+.animate-scroll,
+.animate-trigger,
+.float,
+.float-path {
+  animation-fill-mode: both;
+}
+
+/* ===========================================
+ * Stagger Support
+ * =========================================== */
+
+.stagger {
+  --_stagger-amount: var(--stagger-amount, 0.1s);
+}
+
+.stagger > * {
+  /* Default: no stagger (index 0). JS (applyRowStagger) sets a per-item
+     --_stagger-index inline, which wins. Where sibling-index() is supported
+     it provides a JS-free fallback via the @supports block below. */
+  --_stagger-index: 0;
+  animation-delay: calc(var(--_stagger-index) * var(--_stagger-amount));
+}
+
+/* sibling-index() is near-baseline (lacking only Firefox as of 2026). Guarded so
+   that on unsupported engines the declaration is skipped and delay stays 0
+   (items animate together) rather than producing an invalid animation-delay. */
+@supports (--x: sibling-index()) {
+  .stagger > * {
+    --_stagger-index: sibling-index();
+  }
+}
+
+/* ===========================================
+ * Utility Classes
+ * =========================================== */
+
+/* Scroll-based height adjustment (for sticky headers, etc.) */
+.scroll-size {
+  animation: layout linear both;
+  animation-timeline: scroll();
+}
+
+/* Text reveal effect */
+/* Text reveal — scroll-driven two-tone fill.
+   Text starts in --text-reveal-color-from and fills to --text-reveal-color-to
+   as the element scrolls through the viewport. Pure CSS (no JS dependency).
+
+   Robustness: background-clip:text + transparent color can hide text if the
+   technique is unsupported, so we (a) only apply the clip/transparent inside an
+   @supports guard, and (b) default the visible color to the "from" tone so any
+   failure leaves readable text rather than blank space. Scroll-timeline is also
+   guarded — without it the text simply shows the final (to) color, still legible. */
+.text-reveal {
+  /* Fallback baseline: ordinary visible text in the start color. */
+  color: var(--text-reveal-color-from, currentColor);
+}
+
+@supports ((background-clip: text) or (-webkit-background-clip: text)) {
+  .text-reveal {
+    background: var(
+      --text-reveal-background,
+      linear-gradient(
+        var(--text-reveal-slant, 90deg),
+        var(--text-reveal-color-to) 50%,
+        var(--text-reveal-color-from) 50%
+      )
+    );
+    background-size: 200% 100%;
+    background-position: 100% 0; /* start: showing the "from" half */
+    background-clip: text;
+    -webkit-background-clip: text;
+    color: transparent;
+  }
+}
+
+/* Drive the fill with the scroll timeline only where supported. Without this,
+   the @supports block above still renders the gradient at its start position
+   (readable in the "from" color), so nothing disappears. */
+@supports (animation-timeline: view()) {
+  .text-reveal {
+    animation: bg-position-reveal linear both;
+    animation-timeline: view();
+    animation-range: entry 50% cover 50%;
+    --bg-position-reveal-from: 100% 0;
+    --bg-position-reveal-to: 0% 0;
+  }
+}
+
+/* ===========================================
+ * Tier 1a: Keyframe drivers (animation-name from the effect's --_anim)
+ * =========================================== */
+
+.animate-view {
+  animation-name: var(--_anim);
+  animation-timeline: view();
+  /* Finish the entrance early — by default within the first 20% of the element's
+     ENTRY into the viewport — so it's done just after it appears (fill: both
+     holds the end state). Override the stops via --anim-range; journey effects
+     set their own `entry exit` range and are unaffected. */
+  animation-range: var(--anim-range, entry 0% entry 20%);
+}
+
+.animate-scroll {
+  animation-name: var(--_anim);
+  animation-timeline: scroll();
+}
+
+.animate-trigger {
+  animation-name: var(--_anim);
+  animation-duration: var(--trigger-animation-duration);
+}
+
+/* Fallback: when scroll-driven timelines are unsupported, deferred.ts adds
+   .no-scroll-timeline to <html>. Without a timeline, view()/scroll() animations
+   never advance and elements would stick at their `from` keyframe (e.g.
+   opacity:0, clipped, blurred). Cancel the animation so they render in their
+   natural, fully-visible state. Trigger animations are unaffected (JS-driven). */
+:root.no-scroll-timeline :where(.animate-view, .animate-scroll) {
+  animation: none;
+}
+
+/* ===========================================
+ * Tier 1b: Transition base (state-flip — reversible, interruptible)
+ * `.transition` transitions every animatable property, applying each from a
+ * single current var (--t-<prop>). The generated state variants (hover-<fx> /
+ * active-<fx> in animation-effects.css) set those vars per state, so different
+ * effects bind to different states on one element:
+ *   <div class="transition hover-slide-up active-elevate-up">
+ * Covers compositor + the full paint chain; layout (auto height) is keyframe-only.
+ * =========================================== */
+
+.transition {
+  animation: none; /* state-driven, not keyframe-driven */
+  /* Each property reads the internal --t-<prop> (set per state by the variants),
+     falling back to the SAME --<prop>-from endpoint the keyframes read — so the
+     from/to vars are one shared convention across keyframe and transition modes. */
+  opacity: var(--t-opacity, var(--opacity-from, 1));
+  translate: var(--t-translate-x, var(--translate-x-from, 0))
+    var(--t-translate-y, var(--translate-y-from, 0));
+  scale: var(--t-scale-x, var(--scale-x-from, 1)) var(--t-scale-y, var(--scale-y-from, 1));
+  rotate: var(--t-rotate, var(--rotate-from, 0deg));
+  filter: blur(var(--t-blur, var(--blur-from, 0px)))
+    drop-shadow(var(--t-shadow, var(--shadow-from, 0 0 0 transparent)))
+    brightness(var(--t-brightness, var(--brightness-from, 1)))
+    grayscale(var(--t-grayscale, var(--grayscale-from, 0)))
+    contrast(var(--t-contrast, var(--contrast-from, 1)))
+    saturate(var(--t-saturate, var(--saturate-from, 1))) sepia(var(--t-sepia, var(--sepia-from, 0)))
+    hue-rotate(var(--t-hue-rotate, var(--hue-rotate-from, 0deg)));
+  clip-path: var(--t-clip, var(--clip-from, none));
+  transition:
+    opacity var(--animation-duration) var(--custom-ease-out),
+    translate var(--animation-duration) var(--custom-ease-out),
+    scale var(--animation-duration) var(--custom-ease-out),
+    rotate var(--animation-duration) var(--custom-ease-out),
+    filter var(--animation-duration) var(--custom-ease-out),
+    clip-path var(--animation-duration) var(--custom-ease-out);
+}
+
+/* Respect reduced-motion: drop keyframes, transitions, and continuous floats so
+   elements settle at their natural resolved state. Plain selectors + !important
+   so this reliably overrides the driver/float rules (a legitimate a11y override). */
+@media (prefers-reduced-motion: reduce) {
+  .animate-view,
+  .animate-scroll,
+  .animate-trigger,
+  .float,
+  .float-path {
+    animation: none !important;
+  }
+  .transition {
+    transition: none !important;
+  }
+}
+
+/* ===========================================
+ * Float Presets — Waypoint-based
+ * Each sets float-x / float-y waypoint vars + easing
+ * =========================================== */
+
+/* Circular orbit (clockwise) */
+.float-circular {
+  --float-easing: var(--ease-float-sine);
+  --float-y-0: calc(-1 * var(--float-radius, 10px));
+  --float-x-25: var(--float-radius, 10px);
+  --float-y-50: var(--float-radius, 10px);
+  --float-x-75: calc(-1 * var(--float-radius, 10px));
+}
+
+/* Circular orbit (counter-clockwise) */
+.float-circular-ccw {
+  --float-easing: var(--ease-float-sine);
+  --float-y-0: calc(-1 * var(--float-radius, 10px));
+  --float-x-25: calc(-1 * var(--float-radius, 10px));
+  --float-y-50: var(--float-radius, 10px);
+  --float-x-75: var(--float-radius, 10px);
+}
+
+/* Figure-8 (lemniscate approximation) */
+.float-figure-8 {
+  --float-easing: var(--ease-float-sine);
+  --float-x-25: var(--float-radius, 15px);
+  --float-y-25: calc(-1 * var(--float-radius, 15px) * 0.5);
+  --float-x-75: calc(-1 * var(--float-radius, 15px));
+  --float-y-75: calc(var(--float-radius, 15px) * 0.5);
+}
+
+/* Vertical bounce (1D, y-axis only) */
+.float-bounce-y {
+  --float-easing: var(--ease-float-bounce);
+  --float-y-0: calc(-1 * var(--float-distance, 8px));
+  --float-y-50: var(--float-distance, 8px);
+}
+
+/* Horizontal drift (1D, x-axis only) */
+.float-drift-x {
+  --float-easing: var(--ease-float-bounce);
+  --float-x-0: calc(-1 * var(--float-distance, 10px));
+  --float-x-50: var(--float-distance, 10px);
+}
+
+/* Gentle drift (subtle organic movement) */
+.float-gentle {
+  --float-easing: var(--ease-float-sine);
+  --float-x-0: calc(-1 * var(--float-radius, 5px));
+  --float-y-0: calc(-1 * var(--float-radius, 5px) * 0.7);
+  --float-x-25: calc(var(--float-radius, 5px) * 0.5);
+  --float-y-25: calc(-1 * var(--float-radius, 5px) * 0.3);
+  --float-x-50: calc(var(--float-radius, 5px) * 0.8);
+  --float-y-50: calc(var(--float-radius, 5px) * 0.6);
+  --float-x-75: calc(-1 * var(--float-radius, 5px) * 0.3);
+  --float-y-75: var(--float-radius, 5px);
+}
+
+/* ===========================================
+ * Float Presets — Path-based
+ * Uses offset-path + offset-distance
+ * =========================================== */
+
+.float-path {
+  offset-path: var(--float-path, circle(30px));
+  offset-rotate: var(--float-rotate, 0deg);
+  animation-name: float-path;
+  animation-duration: var(--float-duration, 4s);
+  animation-timing-function: var(--float-easing, linear);
+  animation-iteration-count: var(--float-iterations, infinite);
+}
+
+.float-path-circle {
+  --float-path: circle(var(--float-radius, 30px));
+}
+
+.float-path-ellipse {
+  --float-path: ellipse(var(--float-radius-x, 40px) var(--float-radius-y, 20px));
+}
+
+/* ===========================================
+ * Float Modifiers
+ * =========================================== */
+
+.float-slow {
+  --float-duration: 8s;
+}
+
+.float-fast {
+  --float-duration: 2s;
+}
+
+.float-linear {
+  --float-easing: linear;
+}
+
+.float-organic {
+  --float-easing: ease-in-out;
+}

package/css/global.css

@@ -0,0 +1,17 @@
+/* Assert a 16px root. The framework's rem-based tokens (type + space scales) are
+   generated on a 16px basis, so a host that resets the root — WordPress themes and
+   resets often ship `:root { font-size: 62.5% }` (1rem = 10px) — would silently
+   shrink the entire system to ~62.5%. `!important` keeps the design system portable
+   and predictable across hosts (Bricks, Astro/Tailwind); browser zoom still scales
+   the page. */
+:root {
+  font-size: 100% !important;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  html {
+    scrollbar-gutter: stable;
+    scroll-behavior: smooth;
+    scroll-padding-block-start: var(--top-offset, 0);
+  }
+}

package/css/index.css

@@ -0,0 +1,58 @@
+@import './global.css';
+@import './animation.css';
+@import './generated/animation-effects.css';
+@import './generated/color.css';
+@import './generated/shadows.css';
+@import './generated/type-tokens.css';
+@import './generated/tokens.css';
+@import './generated/typography.css';
+@import './layout.css';
+/* was layout-extra.css */
+@import './patterns/cluster.css';
+@import './patterns/grouped.css';
+@import './patterns/subgrid.css';
+@import './patterns/masonry.css';
+@import './patterns/media.css';
+@import './patterns/separator.css';
+@import './patterns/sticky.css';
+@import './patterns/stack.css';
+@import './patterns/splitter.css';
+@import './utilities.css';
+@import './generated/patterns.css';
+/* was overlays.css */
+@import './patterns/dialog.css';
+@import './patterns/drawer.css';
+@import './patterns/popover.css';
+@import './patterns/tooltip.css';
+@import './patterns/dropdown.css';
+@import './patterns/split-link.css';
+@import './patterns/sitenav.css';
+@import './patterns/notification.css';
+@import './patterns/lightbox.css';
+@import './patterns/overlay.css';
+/* was forms.css */
+@import './patterns/forms.css';
+@import './patterns/combobox.css';
+/* was content.css */
+@import './patterns/table.css';
+@import './patterns/details.css';
+@import './patterns/comment.css';
+@import './patterns/banner.css';
+@import './patterns/list.css';
+@import './patterns/tree.css';
+/* was typographic.css */
+@import './patterns/pull-quote.css';
+@import './patterns/tag.css';
+@import './patterns/anchor-link.css';
+@import './patterns/icon.css';
+@import './patterns/code.css';
+/* was scroll.css */
+@import './patterns/scroll-based.css';
+@import './patterns/horizontal-scroll.css';
+@import './patterns/scroll-target.css';
+@import './patterns/text-effects.css';
+@import './patterns/svg.css';
+@import './patterns/marquee.css';
+@import './patterns/nav.css';
+@import './patterns/carousel.css';
+@import './patterns/copy.css';