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

package/dist/testing.js

@@ -0,0 +1,588 @@
+import { processDirectives } from "./process.js";
+import { extractVariables } from "./variable-extractor.js";
+export function installNodeConstants() {
+  const N = globalThis.Node || (globalThis.Node = {});
+  if (N.ELEMENT_NODE == null)
+    N.ELEMENT_NODE = 1;
+  if (N.TEXT_NODE == null)
+    N.TEXT_NODE = 3;
+  if (N.COMMENT_NODE == null)
+    N.COMMENT_NODE = 8;
+  if (N.DOCUMENT_NODE == null)
+    N.DOCUMENT_NODE = 9;
+  if (N.DOCUMENT_FRAGMENT_NODE == null)
+    N.DOCUMENT_FRAGMENT_NODE = 11;
+}
+export function shimAttributes(root) {
+  if (!root)
+    return;
+  const els = [root, ...root.querySelectorAll ? Array.from(root.querySelectorAll("*")) : []];
+  for (const el of els) {
+    if (!el || el.nodeType !== 1 || el.__attrShimmed)
+      continue;
+    const map = el.attributes;
+    if (!(map instanceof Map))
+      continue;
+    el.__attrMap = map;
+    Object.defineProperty(el, "attributes", {
+      configurable: !0,
+      get() {
+        const m = el.__attrMap, arr = [];
+        let i = 0;
+        for (const [name, value] of m)
+          arr[i++] = {
+            name,
+            value,
+            *[Symbol.iterator]() {
+              yield name;
+              yield value;
+            }
+          };
+        arr.length = i;
+        arr.get = (k) => m.get(k);
+        arr.set = (k, v) => m.set(k, v);
+        arr.delete = (k) => m.delete(k);
+        arr.has = (k) => m.has(k);
+        arr.keys = () => m.keys();
+        arr.values = () => m.values();
+        arr.entries = () => m.entries();
+        arr.forEach = (cb) => m.forEach(cb);
+        Object.defineProperty(arr, "size", { get: () => m.size });
+        arr.item = (n) => arr[n] || null;
+        arr.getNamedItem = (k) => m.has(k) ? { name: k, value: m.get(k) } : null;
+        return arr;
+      }
+    });
+    el.__attrShimmed = !0;
+  }
+}
+export function setupStxTestDom() {
+  installNodeConstants();
+  if (typeof globalThis.requestAnimationFrame > "u")
+    globalThis.requestAnimationFrame = (cb) => setTimeout(cb, 0);
+}
+export function flushEffects(ms = 30) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function render(template, options = {}) {
+  const context = {
+    ...options.context,
+    props: options.props || {}
+  };
+  if (options.mocks)
+    Object.assign(context, options.mocks);
+  if (options.slots)
+    context.__slots__ = options.slots;
+  let processedTemplate = template;
+  const serverScriptRe = /<script\s+server\b[^>]*>([\s\S]*?)<\/script>/gi;
+  let match;
+  while ((match = serverScriptRe.exec(template)) !== null) {
+    const scriptBody = match[1];
+    await extractVariables(scriptBody, context, "test.stx");
+    processedTemplate = processedTemplate.replace(match[0], "");
+  }
+  processedTemplate = processedTemplate.replace(/<template\b[^>]*>/gi, "").replace(/<\/template>/gi, "");
+  const dependencies = new Set, stxOptions = {
+    debug: !1,
+    ...options.stxOptions
+  };
+  return await processDirectives(processedTemplate, context, "test.stx", stxOptions, dependencies);
+}
+export async function mount(template, options = {}) {
+  const emittedEvents = {};
+  let currentProps = { ...options.props }, currentData = {};
+  const captureEvent = (event, payload) => {
+    if (!emittedEvents[event])
+      emittedEvents[event] = [];
+    emittedEvents[event].push([payload]);
+  }, context = {
+    ...options.context,
+    props: currentProps,
+    $emit: captureEvent
+  };
+  let processedTemplate = template;
+  const serverScriptRe = /<script\s+server\b[^>]*>([\s\S]*?)<\/script>/gi;
+  let scriptMatch;
+  while ((scriptMatch = serverScriptRe.exec(template)) !== null) {
+    const scriptBody = scriptMatch[1];
+    await extractVariables(scriptBody, context, "test.stx");
+    processedTemplate = processedTemplate.replace(scriptMatch[0], "");
+  }
+  const plainScriptRe = /<script\b(?!\s+(?:server|client|src))[^>]*>([\s\S]*?)<\/script>/gi;
+  while ((scriptMatch = plainScriptRe.exec(processedTemplate)) !== null) {
+    const scriptBody = scriptMatch[1];
+    await extractVariables(scriptBody, context, "test.stx");
+    processedTemplate = processedTemplate.replace(scriptMatch[0], "");
+  }
+  processedTemplate = processedTemplate.replace(/<template\b[^>]*>/gi, "").replace(/<\/template>/gi, "");
+  const dependencies = new Set, stxOptions = {
+    debug: !1,
+    ...options.stxOptions
+  };
+  let html = await processDirectives(processedTemplate, context, "test.stx", stxOptions, dependencies), container;
+  if (options.attachTo)
+    container = typeof options.attachTo === "string" ? document.querySelector(options.attachTo) || document.createElement("div") : options.attachTo;
+  else {
+    container = document.createElement("div");
+    container.id = `stx-test-${Date.now()}`;
+  }
+  container.innerHTML = html;
+  const rerender = async () => {
+    context.props = currentProps;
+    Object.assign(context, currentData);
+    html = await processDirectives(template, context, "test.stx", stxOptions, dependencies);
+    container.innerHTML = html;
+  }, createElementWrapper = (el) => ({
+    element: el,
+    html: () => el.innerHTML,
+    text: () => el.textContent || "",
+    find: (selector) => {
+      const found = el.querySelector(selector);
+      return found ? createElementWrapper(found) : null;
+    },
+    findAll: (selector) => {
+      return Array.from(el.querySelectorAll(selector)).map(createElementWrapper);
+    },
+    exists: () => document.body.contains(el),
+    isVisible: () => {
+      const style = window.getComputedStyle(el);
+      return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+    },
+    attributes: (name) => {
+      if (name)
+        return el.getAttribute(name);
+      const attrs = {};
+      for (const attr of el.attributes)
+        attrs[attr.name] = attr.value;
+      return attrs;
+    },
+    classes: (name) => {
+      if (name)
+        return el.classList.contains(name);
+      return Array.from(el.classList);
+    },
+    trigger: async (event, payload) => {
+      const evt = new CustomEvent(event, {
+        bubbles: !0,
+        cancelable: !0,
+        detail: payload
+      });
+      el.dispatchEvent(evt);
+      captureEvent(event, payload);
+      await nextTick();
+    },
+    getValue: () => {
+      if (el instanceof HTMLInputElement) {
+        if (el.type === "checkbox")
+          return el.checked;
+        if (el.type === "radio")
+          return el.checked;
+        return el.value;
+      }
+      if (el instanceof HTMLSelectElement) {
+        if (el.multiple)
+          return Array.from(el.selectedOptions).map((o) => o.value);
+        return el.value;
+      }
+      if (el instanceof HTMLTextAreaElement)
+        return el.value;
+      return "";
+    },
+    setValue: async (value) => {
+      if (el instanceof HTMLInputElement) {
+        if (el.type === "checkbox" || el.type === "radio")
+          el.checked = value;
+        else
+          el.value = value;
+        el.dispatchEvent(new Event("input", { bubbles: !0 }));
+        el.dispatchEvent(new Event("change", { bubbles: !0 }));
+      } else if (el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) {
+        el.value = value;
+        el.dispatchEvent(new Event("input", { bubbles: !0 }));
+        el.dispatchEvent(new Event("change", { bubbles: !0 }));
+      }
+      await nextTick();
+    }
+  }), wrapper = {
+    element: container.firstElementChild || container,
+    html: () => container.innerHTML,
+    text: () => container.textContent || "",
+    find: (selector) => {
+      const el = container.querySelector(selector);
+      return el ? createElementWrapper(el) : null;
+    },
+    findAll: (selector) => {
+      return Array.from(container.querySelectorAll(selector)).map(createElementWrapper);
+    },
+    findComponent: (name) => {
+      if (container.querySelector(`[data-component="${name}"], ${name.toLowerCase()}, ${toKebabCase(name)}`))
+        return wrapper;
+      return null;
+    },
+    findAllComponents: (name) => {
+      const els = container.querySelectorAll(`[data-component="${name}"], ${name.toLowerCase()}, ${toKebabCase(name)}`);
+      return Array.from(els).map(() => wrapper);
+    },
+    exists: (selector) => {
+      if (selector)
+        return container.querySelector(selector) !== null;
+      return container.children.length > 0;
+    },
+    isVisible: () => {
+      const el = container.firstElementChild;
+      if (!el)
+        return !1;
+      const style = window.getComputedStyle(el);
+      return style.display !== "none" && style.visibility !== "hidden";
+    },
+    attributes: (selectorOrName) => {
+      if (!selectorOrName) {
+        const el = container.firstElementChild;
+        if (!el)
+          return {};
+        const attrs = {};
+        for (const attr of el.attributes)
+          attrs[attr.name] = attr.value;
+        return attrs;
+      }
+      const found = container.querySelector(selectorOrName);
+      if (found) {
+        const attrs = {};
+        for (const attr of found.attributes)
+          attrs[attr.name] = attr.value;
+        return attrs;
+      }
+      const el = container.firstElementChild;
+      return el ? el.getAttribute(selectorOrName) : null;
+    },
+    classes: (selectorOrName) => {
+      const getClasses = (el) => (el.className || "").split(/\s+/).filter(Boolean);
+      if (!selectorOrName) {
+        const el = container.firstElementChild;
+        if (!el)
+          return [];
+        return getClasses(el);
+      }
+      const found = container.querySelector(selectorOrName);
+      if (found)
+        return getClasses(found);
+      const el = container.firstElementChild;
+      if (el)
+        return getClasses(el).includes(selectorOrName);
+      return !1;
+    },
+    props: (name) => {
+      if (name)
+        return currentProps[name];
+      return { ...currentProps };
+    },
+    emitted: (event) => {
+      if (event)
+        return emittedEvents[event];
+      return { ...emittedEvents };
+    },
+    setProps: async (props) => {
+      currentProps = { ...currentProps, ...props };
+      await rerender();
+    },
+    setData: async (data) => {
+      currentData = { ...currentData, ...data };
+      await rerender();
+    },
+    trigger: async (event, payload) => {
+      const el = container.firstElementChild;
+      if (el) {
+        const evt = new CustomEvent(event, {
+          bubbles: !0,
+          cancelable: !0,
+          detail: payload
+        });
+        el.dispatchEvent(evt);
+        captureEvent(event, payload);
+      }
+      await nextTick();
+    },
+    getValue: () => {
+      const el = container.querySelector("input, select, textarea");
+      if (el)
+        return createElementWrapper(el).getValue();
+      return "";
+    },
+    setValue: async (value) => {
+      const el = container.querySelector("input, select, textarea");
+      if (el)
+        await createElementWrapper(el).setValue(value);
+    },
+    unmount: () => {
+      container.innerHTML = "";
+      if (container.parentElement)
+        container.parentElement.removeChild(container);
+    },
+    vm: {
+      $nextTick: nextTick
+    }
+  };
+  return wrapper;
+}
+export const fireEvent = {
+  async click(target, options) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    const event = new MouseEvent("click", {
+      bubbles: !0,
+      cancelable: !0,
+      ...options
+    });
+    el.dispatchEvent(event);
+    await nextTick();
+  },
+  async dblClick(target, options) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    const event = new MouseEvent("dblclick", {
+      bubbles: !0,
+      cancelable: !0,
+      ...options
+    });
+    el.dispatchEvent(event);
+    await nextTick();
+  },
+  async input(target, value) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    el.value = value;
+    el.dispatchEvent(new Event("input", { bubbles: !0 }));
+    await nextTick();
+  },
+  async change(target, value) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    if (value !== void 0)
+      el.value = value;
+    el.dispatchEvent(new Event("change", { bubbles: !0 }));
+    await nextTick();
+  },
+  async submit(target) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    const event = new Event("submit", { bubbles: !0, cancelable: !0 });
+    el.dispatchEvent(event);
+    await nextTick();
+  },
+  async focus(target) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    el.focus();
+    el.dispatchEvent(new FocusEvent("focus", { bubbles: !0 }));
+    await nextTick();
+  },
+  async blur(target) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    el.blur();
+    el.dispatchEvent(new FocusEvent("blur", { bubbles: !0 }));
+    await nextTick();
+  },
+  async keyDown(target, key, options) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    const event = new KeyboardEvent("keydown", {
+      bubbles: !0,
+      cancelable: !0,
+      key,
+      ...options
+    });
+    el.dispatchEvent(event);
+    await nextTick();
+  },
+  async keyUp(target, key, options) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    const event = new KeyboardEvent("keyup", {
+      bubbles: !0,
+      cancelable: !0,
+      key,
+      ...options
+    });
+    el.dispatchEvent(event);
+    await nextTick();
+  },
+  async custom(target, eventName, options) {
+    const el = getElement(target);
+    if (!el)
+      return;
+    const event = new CustomEvent(eventName, {
+      bubbles: options?.bubbles ?? !0,
+      cancelable: options?.cancelable ?? !0,
+      detail: options?.detail
+    });
+    el.dispatchEvent(event);
+    await nextTick();
+  }
+}, matchers = {
+  toContainText(wrapper, text) {
+    return wrapper.text().includes(text);
+  },
+  toHaveClass(wrapper, className) {
+    return wrapper.classes(className);
+  },
+  toHaveAttribute(wrapper, name, value) {
+    const attr = wrapper.attributes(name);
+    if (value !== void 0)
+      return attr === value;
+    return attr !== null;
+  },
+  toBeVisible(wrapper) {
+    return wrapper.isVisible();
+  },
+  toExist(wrapper) {
+    return wrapper !== null && wrapper.exists();
+  },
+  toHaveEmitted(wrapper, event, times) {
+    const emitted = wrapper.emitted(event);
+    if (!emitted)
+      return !1;
+    if (times !== void 0)
+      return emitted.length === times;
+    return emitted.length > 0;
+  },
+  toHaveEmittedWith(wrapper, event, payload) {
+    const emitted = wrapper.emitted(event);
+    if (!emitted)
+      return !1;
+    return emitted.some((args) => JSON.stringify(args[0]) === JSON.stringify(payload));
+  }
+};
+export function nextTick() {
+  return new Promise((resolve) => {
+    if (typeof requestAnimationFrame < "u")
+      requestAnimationFrame(() => resolve());
+    else
+      setTimeout(resolve, 0);
+  });
+}
+export async function waitFor(condition, options = {}) {
+  const { timeout = 1000, interval = 50 } = options, start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (await condition())
+      return;
+    await new Promise((r) => setTimeout(r, interval));
+  }
+  throw Error(`waitFor timed out after ${timeout}ms`);
+}
+export async function waitForElement(wrapper, selector, options = {}) {
+  const { timeout = 1000 } = options;
+  await waitFor(() => wrapper.find(selector) !== null, { timeout });
+  return wrapper.find(selector);
+}
+export async function flushPromises() {
+  await new Promise((r) => setTimeout(r, 0));
+  await nextTick();
+}
+export function createMockFn(impl) {
+  const calls = [], results = [];
+  let implementation = impl;
+  const fn = (...args) => {
+    calls.push(args);
+    if (implementation) {
+      const result = implementation(...args);
+      results.push(result);
+      return result;
+    }
+    return;
+  };
+  fn.mock = {
+    calls,
+    results
+  };
+  fn.calls = calls;
+  fn.reset = () => {
+    calls.length = 0;
+    results.length = 0;
+    implementation = impl;
+    return fn;
+  };
+  fn.mockImplementation = (newImpl) => {
+    implementation = newImpl;
+    return fn;
+  };
+  fn.mockReturnValue = (value) => {
+    implementation = () => value;
+    return fn;
+  };
+  fn.mockClear = () => {
+    calls.length = 0;
+    results.length = 0;
+    return fn;
+  };
+  fn.mockReset = () => {
+    calls.length = 0;
+    results.length = 0;
+    implementation = void 0;
+    return fn;
+  };
+  return fn;
+}
+export function createMockStore(initialState) {
+  const initial = { ...initialState };
+  let state = { ...initialState };
+  const history = [{ ...state }], listeners = new Set, notify = () => {
+    for (const listener of listeners)
+      listener({ ...state });
+  };
+  return {
+    getState() {
+      return { ...state };
+    },
+    setState(partial) {
+      state = { ...state, ...partial };
+      history.push({ ...state });
+      notify();
+    },
+    reset() {
+      state = { ...initial };
+      history.length = 0;
+      history.push({ ...state });
+      notify();
+    },
+    getHistory() {
+      return history.map((s) => ({ ...s }));
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+function getElement(target) {
+  if (!target)
+    return null;
+  if (target instanceof HTMLElement)
+    return target;
+  return target.element;
+}
+function toKebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+export function createTestContext(options = {}) {
+  return {
+    props: options.props || {},
+    context: options.context || {},
+    mocks: Object.entries(options.mocks || {}).reduce((acc, [key, value]) => {
+      acc[key] = typeof value === "function" ? createMockFn() : value;
+      return acc;
+    }, {})
+  };
+}
+export function cleanup() {
+  document.querySelectorAll('[id^="stx-test-"]').forEach((el) => el.remove());
+}

package/dist/theme-tokens.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Role-named colours, so a component can say what a colour is FOR.
+ *
+ * `@stacksjs/components` named palette shades directly — `bg-gray-100`,
+ * `text-gray-600`, `ring-indigo-600` — with a `dark:` variant beside each. That
+ * renders correctly and is impossible for a host app to redirect by meaning: you
+ * can remap `gray`, but you cannot say "every border in the library comes from
+ * `--stx-line`", because nothing distinguishes a gray that is a border from a
+ * gray that is muted text (stacksjs/stx#1930).
+ *
+ * These tokens are added to the BASE theme rather than shipped as an opt-in
+ * preset. That matters for one reason: a component that says `text-fg-muted`
+ * must resolve in every app, or adopting the component library would silently
+ * require a config change and render unstyled without it. Adding names is purely
+ * additive — no existing utility changes, and no opacity modifier on an existing
+ * palette colour turns into `color-mix()`.
+ *
+ * ## Where the values come from
+ *
+ * Each token names a shade in css's own palette rather than carrying a hex
+ * value, and the light/dark pairs are the ones the component library already
+ * used most — measured, not invented:
+ *
+ *     text-gray-900 dark:text-gray-100   ×70   ->  text-fg
+ *     text-gray-500 dark:text-gray-400   ×24   ->  text-fg-soft
+ *     border-gray-200 dark:border-gray-700 ×21 ->  border-line
+ *
+ * So migrating a component to a token is appearance-preserving wherever its
+ * pairing was the dominant one, and the defaults stay in step with the palette
+ * because they are resolved from it rather than copied.
+ *
+ * ## How dark mode works
+ *
+ * Each token resolves to `var(--stx-<name>, <light value>)`, and
+ * {@link semanticTokenCSS} emits `:root` and `.dark` blocks that set the
+ * variable. So `text-fg-muted` is one class that is correct in both modes, and
+ * an app overrides a role by setting the variable — at runtime, with no rebuild.
+ *
+ * The fallback is deliberately the LIGHT value. If the variable block ever fails
+ * to reach a page, light mode is still correct and dark mode falls back to the
+ * light colour: degraded, but readable. The alternative — no fallback — would
+ * render the token as an invalid colour and take the whole component's styling
+ * with it.
+ *
+ * @module theme-tokens
+ */
+/** A role, and the palette shades that back it in each mode. */
+export interface SemanticToken {
+    /** Shade reference, e.g. `gray-900`. Resolved against the live palette. */
+    light: string;
+    dark: string;
+    /** What the role means, for the generated docs and for anyone reading here. */
+    description: string;
+}
+/**
+ * The role vocabulary.
+ *
+ * Five text roles rather than the usual three because the library genuinely
+ * distinguishes five: 900, 700, 600, 500 and 400 all appear as body-ish text
+ * with different dark partners. Collapsing them here would have been a redesign
+ * rather than a migration.
+ */
+export declare const SEMANTIC_TOKENS: Record<string, SemanticToken>;
+/** The CSS custom property that backs a role. */
+export declare function tokenVariable(name: string): string;
+type Palette = Record<string, unknown>;
+/**
+ * The palette entries to merge into `theme.colors`.
+ *
+ * Every entry is `var(--stx-<name>, <light value>)`, so the name works as an
+ * ordinary utility (`bg-surface`, `text-fg-muted`, `ring-line-strong`) and an
+ * app can move it by setting the variable.
+ */
+export declare function semanticColors(palette: Palette): Record<string, string>;
+/**
+ * The `:root` / `.dark` block that gives each role its value per mode.
+ *
+ * Emitted ahead of the generated utilities so an app's own stylesheet — which
+ * comes after — can override any of it without a specificity fight.
+ *
+ * `.dark` matches the class strategy the rest of stx uses (`dark:` variants
+ * compile to `.dark .dark\:x`), so a token and a `dark:` utility on the same
+ * page agree about what dark mode is.
+ */
+export declare function semanticTokenCSS(palette: Palette): string;
+/** Every variable a role token reads, for documentation and tooling. */
+export declare function semanticTokenNames(): string[];
+export {};