@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/theme-tokens.js

@@ -0,0 +1,71 @@
+export const SEMANTIC_TOKENS = {
+  fg: { light: "gray-900", dark: "gray-100", description: "Primary text" },
+  "fg-strong": { light: "gray-700", dark: "gray-300", description: "Labels, secondary headings" },
+  "fg-muted": { light: "gray-600", dark: "gray-400", description: "Supporting text" },
+  "fg-soft": { light: "gray-500", dark: "gray-400", description: "De-emphasised text" },
+  "fg-subtle": { light: "gray-400", dark: "gray-500", description: "Placeholders, disabled text" },
+  surface: { light: "gray-50", dark: "gray-800", description: "Page and panel background" },
+  "surface-raised": { light: "gray-100", dark: "gray-700", description: "Cards, popovers" },
+  "surface-sunken": { light: "gray-200", dark: "gray-700", description: "Wells, track backgrounds" },
+  line: { light: "gray-200", dark: "gray-700", description: "Default border, divider" },
+  "line-strong": { light: "gray-300", dark: "gray-600", description: "Input border, focus ring track" },
+  accent: { light: "indigo-600", dark: "indigo-400", description: "Primary action, selected state" },
+  info: { light: "blue-600", dark: "blue-400", description: "Informational emphasis, links" },
+  danger: { light: "red-600", dark: "red-400", description: "Errors, destructive actions" },
+  success: { light: "green-600", dark: "green-400", description: "Confirmation" },
+  warning: { light: "yellow-500", dark: "yellow-400", description: "Caution" },
+  "accent-solid": { light: "indigo-600", dark: "indigo-500", description: "Primary button fill" },
+  "info-solid": { light: "blue-600", dark: "blue-500", description: "Informational fill" },
+  "danger-solid": { light: "red-600", dark: "red-500", description: "Destructive button fill" },
+  "success-solid": { light: "green-600", dark: "green-500", description: "Confirmation fill" }
+};
+export function tokenVariable(name) {
+  return `--stx-${name}`;
+}
+function resolveShade(palette, reference) {
+  const split = reference.lastIndexOf("-");
+  if (split === -1)
+    return typeof palette[reference] === "string" ? palette[reference] : void 0;
+  const family = palette[reference.slice(0, split)];
+  if (!family || typeof family !== "object")
+    return;
+  const value = family[reference.slice(split + 1)];
+  return typeof value === "string" ? value : void 0;
+}
+export function semanticColors(palette) {
+  const colors = {};
+  for (const [name, token] of Object.entries(SEMANTIC_TOKENS)) {
+    const light = resolveShade(palette, token.light);
+    if (light === void 0)
+      continue;
+    colors[name] = `var(${tokenVariable(name)}, ${light})`;
+  }
+  return colors;
+}
+export function semanticTokenCSS(palette) {
+  const light = [], dark = [];
+  for (const [name, token] of Object.entries(SEMANTIC_TOKENS)) {
+    const lightValue = resolveShade(palette, token.light), darkValue = resolveShade(palette, token.dark);
+    if (lightValue === void 0)
+      continue;
+    light.push(`  ${tokenVariable(name)}: ${lightValue};`);
+    if (darkValue !== void 0)
+      dark.push(`  ${tokenVariable(name)}: ${darkValue};`);
+  }
+  if (light.length === 0)
+    return "";
+  return [
+    "/* stx role tokens \u2014 override any of these to re-theme by meaning. */",
+    ":root {",
+    ...light,
+    "}",
+    ".dark {",
+    ...dark,
+    "}",
+    ""
+  ].join(`
+`);
+}
+export function semanticTokenNames() {
+  return Object.keys(SEMANTIC_TOKENS).map(tokenVariable);
+}

package/dist/transitions.d.ts

@@ -0,0 +1,99 @@
+/**
+ * STX Transitions
+ *
+ * Vue-inspired transition system for enter/leave animations.
+ * Supports CSS transitions, CSS animations, and JavaScript hooks.
+ *
+ * @module transitions
+ *
+ * @example
+ * ```html
+ * @transition(name: 'fade')
+ *   @if (visible)
+ *     <div class="modal">Content</div>
+ *   @endif
+ * @endtransition
+ * ```
+ *
+ * CSS classes applied:
+ * - `.fade-enter-from` - Starting state for enter
+ * - `.fade-enter-active` - Active state during enter
+ * - `.fade-enter-to` - Ending state for enter
+ * - `.fade-leave-from` - Starting state for leave
+ * - `.fade-leave-active` - Active state during leave
+ * - `.fade-leave-to` - Ending state for leave
+ */
+export interface TransitionOptions {
+    /** Transition name (used for CSS class prefix) */
+    name?: string;
+    /** Duration in milliseconds */
+    duration?: number | {
+        enter: number;
+        leave: number;
+    };
+    /** CSS transition timing function */
+    easing?: string;
+    /** Transition mode: 'in-out' or 'out-in' */
+    mode?: 'in-out' | 'out-in' | 'default';
+    /** Use CSS animations instead of transitions */
+    css?: boolean;
+    /** Custom enter class */
+    enterClass?: string;
+    /** Custom enter-active class */
+    enterActiveClass?: string;
+    /** Custom enter-to class */
+    enterToClass?: string;
+    /** Custom leave class */
+    leaveClass?: string;
+    /** Custom leave-active class */
+    leaveActiveClass?: string;
+    /** Custom leave-to class */
+    leaveToClass?: string;
+    /** JavaScript hooks */
+    onBeforeEnter?: (el: Element) => void;
+    onEnter?: (el: Element, done: () => void) => void;
+    onAfterEnter?: (el: Element) => void;
+    onEnterCancelled?: (el: Element) => void;
+    onBeforeLeave?: (el: Element) => void;
+    onLeave?: (el: Element, done: () => void) => void;
+    onAfterLeave?: (el: Element) => void;
+    onLeaveCancelled?: (el: Element) => void;
+}
+export interface TransitionState {
+    isEntering: boolean;
+    isLeaving: boolean;
+    isCancelled: boolean;
+}
+/**
+ * Perform an enter transition on an element.
+ */
+export declare function performEnter(el: Element, options?: TransitionOptions): Promise<void>;
+/**
+ * Perform a leave transition on an element.
+ */
+export declare function performLeave(el: Element, options?: TransitionOptions): Promise<void>;
+/**
+ * Process @transition directives in templates.
+ *
+ * Syntax:
+ *   @transition(name: 'fade')
+ *   @transition(name: 'slide', duration: 300)
+ *   @transition(name: 'fade', mode: 'out-in')
+ */
+export declare function processTransitionDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Generate CSS for common transition presets.
+ */
+export declare function generateTransitionCSS(): string;
+/**
+ * Generate the client-side transition runtime.
+ */
+export declare function generateTransitionRuntime(): string;
+/**
+ * Process @transition attribute on elements.
+ *
+ * Usage:
+ *   <div @transition.fade="visible">Content</div>
+ *   <div @transition.slide-up.300="isOpen">Content</div>
+ */
+export declare function processTransitionAttributes(template: string): string;

package/dist/transitions.js

@@ -0,0 +1,443 @@
+function getTransitionClasses(name, options = {}) {
+  return {
+    enterFrom: options.enterClass || `${name}-enter-from`,
+    enterActive: options.enterActiveClass || `${name}-enter-active`,
+    enterTo: options.enterToClass || `${name}-enter-to`,
+    leaveFrom: options.leaveClass || `${name}-leave-from`,
+    leaveActive: options.leaveActiveClass || `${name}-leave-active`,
+    leaveTo: options.leaveToClass || `${name}-leave-to`
+  };
+}
+function getTransitionDuration(el) {
+  const style = getComputedStyle(el), transitionDuration = style.transitionDuration || "0s", animationDuration = style.animationDuration || "0s", parseDuration = (str) => {
+    const match = str.match(/^([\d.]+)(s|ms)?$/);
+    if (!match)
+      return 0;
+    const value = parseFloat(match[1]);
+    return (match[2] || "s") === "ms" ? value : value * 1000;
+  };
+  return Math.max(parseDuration(transitionDuration), parseDuration(animationDuration));
+}
+function whenTransitionEnds(el, expectedDuration) {
+  return new Promise((resolve) => {
+    const duration = expectedDuration ?? getTransitionDuration(el);
+    if (duration === 0) {
+      resolve();
+      return;
+    }
+    let resolved = !1;
+    const done = () => {
+      if (resolved)
+        return;
+      resolved = !0;
+      el.removeEventListener("transitionend", onEnd);
+      el.removeEventListener("animationend", onEnd);
+      resolve();
+    }, onEnd = (e) => {
+      if (e.target === el)
+        done();
+    };
+    el.addEventListener("transitionend", onEnd);
+    el.addEventListener("animationend", onEnd);
+    setTimeout(done, duration + 50);
+  });
+}
+function forceReflow(el) {
+  el.offsetHeight;
+}
+export async function performEnter(el, options = {}) {
+  const name = options.name || "stx", classes = getTransitionClasses(name, options), duration = typeof options.duration === "object" ? options.duration.enter : options.duration;
+  options.onBeforeEnter?.(el);
+  el.classList.add(classes.enterFrom);
+  el.classList.add(classes.enterActive);
+  forceReflow(el);
+  el.classList.remove(classes.enterFrom);
+  el.classList.add(classes.enterTo);
+  if (options.onEnter)
+    await new Promise((resolve) => {
+      options.onEnter(el, resolve);
+    });
+  else
+    await whenTransitionEnds(el, duration);
+  el.classList.remove(classes.enterActive);
+  el.classList.remove(classes.enterTo);
+  options.onAfterEnter?.(el);
+}
+export async function performLeave(el, options = {}) {
+  const name = options.name || "stx", classes = getTransitionClasses(name, options), duration = typeof options.duration === "object" ? options.duration.leave : options.duration;
+  options.onBeforeLeave?.(el);
+  el.classList.add(classes.leaveFrom);
+  el.classList.add(classes.leaveActive);
+  forceReflow(el);
+  el.classList.remove(classes.leaveFrom);
+  el.classList.add(classes.leaveTo);
+  if (options.onLeave)
+    await new Promise((resolve) => {
+      options.onLeave(el, resolve);
+    });
+  else
+    await whenTransitionEnds(el, duration);
+  el.classList.remove(classes.leaveActive);
+  el.classList.remove(classes.leaveTo);
+  options.onAfterLeave?.(el);
+}
+export function processTransitionDirectives(template, _context = {}, _filePath) {
+  const transitionRegex = /@transition\s*\(([^)]*)\)([\s\S]*?)@endtransition/gi;
+  return template.replace(transitionRegex, (_match, optionsStr, content) => {
+    const options = parseTransitionOptions(optionsStr), name = options.name || "stx", duration = options.duration || 300, transitionId = `stx-transition-${Math.random().toString(36).slice(2, 9)}`;
+    return `
+<div
+  class="stx-transition-wrapper"
+  data-transition="${name}"
+  data-transition-id="${transitionId}"
+  data-transition-duration="${duration}"
+  ${options.mode ? `data-transition-mode="${options.mode}"` : ""}
+>
+  ${content.trim()}
+</div>
+<script>
+(function() {
+  const wrapper = document.querySelector('[data-transition-id="${transitionId}"]');
+  if (!wrapper) return;
+
+  const name = '${name}';
+  const duration = ${duration};
+
+  // Observe for child changes to trigger transitions
+  const observer = new MutationObserver(function(mutations) {
+    mutations.forEach(function(mutation) {
+      mutation.addedNodes.forEach(function(node) {
+        if (node.nodeType === 1) {
+          window.STX?.transition?.enter(node, { name: name, duration: duration });
+        }
+      });
+      mutation.removedNodes.forEach(function(node) {
+        if (node.nodeType === 1) {
+          // Leave transition handled before removal
+        }
+      });
+    });
+  });
+
+  observer.observe(wrapper, { childList: true });
+
+  // Initial enter transition for existing children
+  Array.from(wrapper.children).forEach(function(child) {
+    window.STX?.transition?.enter(child, { name: name, duration: duration });
+  });
+})();
+</script>
+`;
+  });
+}
+function parseTransitionOptions(optionsStr) {
+  const options = {}, keyValueRegex = /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|(\d+)|(\w+))/g;
+  let match;
+  while ((match = keyValueRegex.exec(optionsStr)) !== null) {
+    const key = match[1], value = match[2] || match[3] || match[4] || match[5];
+    switch (key) {
+      case "name":
+        options.name = value;
+        break;
+      case "duration":
+        options.duration = parseInt(value, 10);
+        break;
+      case "mode":
+        options.mode = value;
+        break;
+      case "easing":
+        options.easing = value;
+        break;
+    }
+  }
+  return options;
+}
+export function generateTransitionCSS() {
+  return `
+/* STX Transition Presets */
+
+/* Fade */
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+.fade-enter-to,
+.fade-leave-from {
+  opacity: 1;
+}
+
+/* Slide Up */
+.slide-up-enter-from,
+.slide-up-leave-to {
+  opacity: 0;
+  transform: translateY(20px);
+}
+.slide-up-enter-active,
+.slide-up-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.slide-up-enter-to,
+.slide-up-leave-from {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* Slide Down */
+.slide-down-enter-from,
+.slide-down-leave-to {
+  opacity: 0;
+  transform: translateY(-20px);
+}
+.slide-down-enter-active,
+.slide-down-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.slide-down-enter-to,
+.slide-down-leave-from {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* Slide Left */
+.slide-left-enter-from {
+  opacity: 0;
+  transform: translateX(20px);
+}
+.slide-left-leave-to {
+  opacity: 0;
+  transform: translateX(-20px);
+}
+.slide-left-enter-active,
+.slide-left-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.slide-left-enter-to,
+.slide-left-leave-from {
+  opacity: 1;
+  transform: translateX(0);
+}
+
+/* Slide Right */
+.slide-right-enter-from {
+  opacity: 0;
+  transform: translateX(-20px);
+}
+.slide-right-leave-to {
+  opacity: 0;
+  transform: translateX(20px);
+}
+.slide-right-enter-active,
+.slide-right-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.slide-right-enter-to,
+.slide-right-leave-from {
+  opacity: 1;
+  transform: translateX(0);
+}
+
+/* Scale */
+.scale-enter-from,
+.scale-leave-to {
+  opacity: 0;
+  transform: scale(0.9);
+}
+.scale-enter-active,
+.scale-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.scale-enter-to,
+.scale-leave-from {
+  opacity: 1;
+  transform: scale(1);
+}
+
+/* Scale Up (grow) */
+.scale-up-enter-from,
+.scale-up-leave-to {
+  opacity: 0;
+  transform: scale(0.5);
+}
+.scale-up-enter-active,
+.scale-up-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.scale-up-enter-to,
+.scale-up-leave-from {
+  opacity: 1;
+  transform: scale(1);
+}
+
+/* Bounce */
+.bounce-enter-active {
+  animation: bounce-in 0.5s;
+}
+.bounce-leave-active {
+  animation: bounce-in 0.5s reverse;
+}
+@keyframes bounce-in {
+  0% {
+    transform: scale(0);
+  }
+  50% {
+    transform: scale(1.1);
+  }
+  100% {
+    transform: scale(1);
+  }
+}
+
+/* Flip */
+.flip-enter-from,
+.flip-leave-to {
+  opacity: 0;
+  transform: perspective(400px) rotateY(90deg);
+}
+.flip-enter-active,
+.flip-leave-active {
+  transition: opacity 0.4s ease, transform 0.4s ease;
+}
+.flip-enter-to,
+.flip-leave-from {
+  opacity: 1;
+  transform: perspective(400px) rotateY(0);
+}
+
+/* Zoom */
+.zoom-enter-from,
+.zoom-leave-to {
+  opacity: 0;
+  transform: scale(0);
+}
+.zoom-enter-active,
+.zoom-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s cubic-bezier(0.175, 0.885, 0.32, 1.275);
+}
+.zoom-enter-to,
+.zoom-leave-from {
+  opacity: 1;
+  transform: scale(1);
+}
+
+/* Collapse (height) */
+.collapse-enter-from,
+.collapse-leave-to {
+  opacity: 0;
+  max-height: 0;
+  overflow: hidden;
+}
+.collapse-enter-active,
+.collapse-leave-active {
+  transition: opacity 0.3s ease, max-height 0.3s ease;
+  overflow: hidden;
+}
+.collapse-enter-to,
+.collapse-leave-from {
+  opacity: 1;
+  max-height: 1000px;
+}
+`;
+}
+export function generateTransitionRuntime() {
+  return `
+// STX Transition Runtime
+(function() {
+  if (typeof window === 'undefined') return;
+
+  window.STX = window.STX || {};
+  window.STX.transition = {
+    // Perform enter transition
+    enter: function(el, options) {
+      options = options || {};
+      const name = options.name || 'stx';
+      const duration = options.duration || 300;
+
+      const classes = {
+        enterFrom: name + '-enter-from',
+        enterActive: name + '-enter-active',
+        enterTo: name + '-enter-to'
+      };
+
+      // Add initial classes
+      el.classList.add(classes.enterFrom);
+      el.classList.add(classes.enterActive);
+
+      // Force reflow
+      void el.offsetHeight;
+
+      // Start transition
+      el.classList.remove(classes.enterFrom);
+      el.classList.add(classes.enterTo);
+
+      // Cleanup after transition
+      setTimeout(function() {
+        el.classList.remove(classes.enterActive);
+        el.classList.remove(classes.enterTo);
+      }, duration + 50);
+
+      return el;
+    },
+
+    // Perform leave transition
+    leave: function(el, options) {
+      return new Promise(function(resolve) {
+        options = options || {};
+        const name = options.name || 'stx';
+        const duration = options.duration || 300;
+
+        const classes = {
+          leaveFrom: name + '-leave-from',
+          leaveActive: name + '-leave-active',
+          leaveTo: name + '-leave-to'
+        };
+
+        // Add initial classes
+        el.classList.add(classes.leaveFrom);
+        el.classList.add(classes.leaveActive);
+
+        // Force reflow
+        void el.offsetHeight;
+
+        // Start transition
+        el.classList.remove(classes.leaveFrom);
+        el.classList.add(classes.leaveTo);
+
+        // Cleanup and resolve after transition
+        setTimeout(function() {
+          el.classList.remove(classes.leaveActive);
+          el.classList.remove(classes.leaveTo);
+          resolve(el);
+        }, duration + 50);
+      });
+    },
+
+    // Toggle with transition
+    toggle: function(el, show, options) {
+      if (show) {
+        el.style.display = '';
+        return this.enter(el, options);
+      }
+else {
+        return this.leave(el, options).then(function() {
+          el.style.display = 'none';
+          return el;
+        });
+      }
+    }
+  };
+
+  console.log('[stx] Transition runtime initialized');
+})();
+`;
+}
+export function processTransitionAttributes(template) {
+  const attrRegex = /@transition\.([a-z-]+)(?:\.(\d+))?="([^"]+)"/gi;
+  return template.replace(attrRegex, (_, name, duration, condition) => {
+    const dur = duration || "300", transitionId = `stx-t-${Math.random().toString(36).slice(2, 7)}`;
+    return `data-stx-transition="${name}" data-stx-transition-duration="${dur}" data-stx-transition-condition="${condition}" data-stx-transition-id="${transitionId}"`;
+  });
+}

package/dist/ts-css-config.d.ts

@@ -0,0 +1,71 @@
+/**
+ * One merge for the css config, used by every render path.
+ *
+ * There were two, and they disagreed (stacksjs/stx#1867). The dev-server path
+ * read only `theme.extend` and pinned the result after the user spread, so a
+ * project writing `theme: { colors: { … } }` the Tailwind-classic way lost its
+ * entire theme with no error and no warning. The serve path shallow-spread the
+ * same key instead, so there the user's `colors` replaced the whole stock
+ * palette — the opposite failure, from the same config file, decided by which
+ * binary rendered the page. It also read only `safelist`, `shortcuts` and
+ * `theme`, dropping `darkMode`, `preflights`, `cssVariables`, `rules`,
+ * `blocklist` and `variants` entirely.
+ *
+ * ## Why theme keys merge instead of replacing
+ *
+ * Tailwind treats a non-`extend` `theme.colors` as a replacement for the
+ * default palette. That semantic depends on generation being driven by
+ * globbing source files: an unused default color costs bytes, so dropping the
+ * stock palette is the point.
+ *
+ * Here it is driven by scanning the rendered page — a color nothing references
+ * generates nothing, so carrying the base palette along is free. Replacement
+ * would mean adding one token to `theme.colors` silently kills `bg-red-500`
+ * everywhere, which is a far worse failure than an unused key costing nothing.
+ * So base and user theme keys deep-merge, and `extend` is passed through
+ * untouched for CSSGenerator to apply on top.
+ *
+ * @module ts-css-config
+ */
+type Dict = Record<string, any>;
+/**
+ * Deep-merge `source` over `target`, recursing into plain objects only.
+ *
+ * Arrays replace rather than concatenate — a theme's `fontFamily: ['Inter',
+ * 'sans-serif']` is a complete stack, not an addition to one.
+ */
+export declare function deepMergeThemes(target: Dict, source: Dict): Dict;
+export interface MergedCssConfig {
+    /** Ready to hand to `new CSSGenerator(...)`. */
+    config: Dict;
+    /** Merged safelist, also needed by callers to pre-generate those classes. */
+    safelist: string[];
+    /** Merged shortcuts, needed by callers that emit grouped shortcut rules. */
+    shortcuts: Record<string, string>;
+    /** Honours the user's `preflight` key (default true). */
+    includePreflight: boolean;
+    /** Honours the user's `minify` key (default false). */
+    minify: boolean;
+    /**
+     * The `:root` / `.dark` declarations backing the role tokens (#1930).
+     *
+     * Returned rather than folded into `preflights` because a project can set
+     * `preflight: false`, and the tokens are not preflight — they are the values
+     * the generated utilities resolve against. Callers prepend this to the CSS
+     * they emit.
+     *
+     * Missing it degrades rather than breaks: every token carries its light value
+     * as the `var()` fallback, so light mode stays correct and dark mode reverts
+     * to the light colour.
+     */
+    tokenCSS: string;
+}
+/**
+ * Merge a project's css config over the package defaults.
+ *
+ * `content` and `output` are stx-owned and pinned last: classes come from
+ * scanning the rendered page, not from globbing, and the CSS is returned rather
+ * than written to disk (#1822).
+ */
+export declare function mergeCssConfig(base?: Dict, user?: Dict): MergedCssConfig;
+export {};