@stacksjs/stx 0.2.175 → 0.2.177

package/dist/crosswind-config.d.ts

@@ -46,6 +46,19 @@ export interface MergedCrosswindConfig {
     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 crosswind config over the package defaults.

package/dist/crosswind-config.js

@@ -1,3 +1,4 @@
+import { semanticColors, semanticTokenCSS } from "./theme-tokens.js";
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -8,7 +9,9 @@ export function deepMergeThemes(target, source) {
   return out;
 }
 export function mergeCrosswindConfig(base = {}, user = {}) {
-  const baseTheme = base.theme || {}, userTheme = user.theme || {}, { extend: userExtend, ...userThemeKeys } = userTheme, { extend: baseExtend, ...baseThemeKeys } = baseTheme, theme = deepMergeThemes(baseThemeKeys, userThemeKeys), extend = deepMergeThemes(baseExtend || {}, userExtend || {});
+  const baseTheme = base.theme || {}, userTheme = user.theme || {}, { extend: userExtend, ...userThemeKeys } = userTheme, { extend: baseExtend, ...baseThemeKeys } = baseTheme, basePalette = baseThemeKeys.colors || {};
+  baseThemeKeys.colors = { ...basePalette, ...semanticColors(basePalette) };
+  const theme = deepMergeThemes(baseThemeKeys, userThemeKeys), extend = deepMergeThemes(baseExtend || {}, userExtend || {});
   if (Object.keys(extend).length > 0)
     theme.extend = extend;
   const safelist = [
@@ -35,6 +38,7 @@ export function mergeCrosswindConfig(base = {}, user = {}) {
     safelist,
     shortcuts,
     includePreflight: user.preflight !== !1,
-    minify: user.minify === !0
+    minify: user.minify === !0,
+    tokenCSS: semanticTokenCSS(basePalette)
   };
 }

package/dist/dev-server/crosswind.js

@@ -324,7 +324,7 @@ export async function generateCrosswindCSS(htmlContent, appDir) {
         configFingerprint = "unhashable";
       }
     }
-    const baseConfig = hw.defaultConfig || hw.config, userConfig = cachedConfig || {}, merged = mergeCrosswindConfig(baseConfig, userConfig), { safelist, includePreflight, minify } = merged, crosswindConfig = merged.config, generator = new hw.CSSGenerator(crosswindConfig);
+    const baseConfig = hw.defaultConfig || hw.config, userConfig = cachedConfig || {}, merged = mergeCrosswindConfig(baseConfig, userConfig), { safelist, includePreflight, minify, tokenCSS } = merged, crosswindConfig = merged.config, generator = new hw.CSSGenerator(crosswindConfig);
     for (const cls of safelist)
       generator.generate(cls);
     for (const className of classes)
@@ -374,6 +374,7 @@ export async function generateCrosswindCSS(htmlContent, appDir) {
         css += `
 @media (prefers-color-scheme: dark) { .dark .${name} { ${darkDecls.join(" ")} } }`;
     }
+    css = tokenCSS + css;
     setLruCache(cacheKey, css);
     writeDiskCache(cacheKey, css);
     return css;

package/dist/edge-runtime.d.ts

@@ -1,3 +1,4 @@
+import { type SetCookieOptions } from './cookie-serialize';
 /**
  * Detect the current edge runtime platform.
  */
@@ -63,15 +64,7 @@ export declare function parseCookies(request: Request): Record<string, string>;
 /**
  * Create a Set-Cookie header value.
  */
-export declare function createCookie(name: string, value: string, options?: {
-    maxAge?: number
-    expires?: Date
-    path?: string
-    domain?: string
-    secure?: boolean
-    httpOnly?: boolean
-    sameSite?: 'Strict' | 'Lax' | 'None'
-  }): string;
+export declare function createCookie(name: string, value: string, options?: SetCookieOptions): string;
 /**
  * JSON response helper.
  */

package/dist/edge-runtime.js

@@ -1,3 +1,4 @@
+import { serializeSetCookie } from "./cookie-serialize.js";
 import nodeProcess from "node:process";
 export function detectRuntime() {
   if (typeof globalThis < "u" && "caches" in globalThis && "CF" in globalThis)
@@ -500,22 +501,7 @@ export function parseCookies(request) {
   return cookies;
 }
 export function createCookie(name, value, options) {
-  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
-  if (options?.maxAge !== void 0)
-    cookie += `; Max-Age=${options.maxAge}`;
-  if (options?.expires)
-    cookie += `; Expires=${options.expires.toUTCString()}`;
-  if (options?.path)
-    cookie += `; Path=${options.path}`;
-  if (options?.domain)
-    cookie += `; Domain=${options.domain}`;
-  if (options?.secure)
-    cookie += "; Secure";
-  if (options?.httpOnly)
-    cookie += "; HttpOnly";
-  if (options?.sameSite)
-    cookie += `; SameSite=${options.sameSite}`;
-  return cookie;
+  return serializeSetCookie(name, value, options);
 }
 export function jsonResponse(data, init) {
   const headers = new Headers(init?.headers);

package/dist/includes.js

@@ -512,14 +512,18 @@ export async function processIncludes(template, context, filePath, options, depe
   }
   const currentFilePath = path.resolve(filePath);
   includeStack.add(currentFilePath);
+  function includeFailure(includePath, message, templateStr, offsetPos) {
+    options.onIncludeError?.({ includePath, templatePath: filePath, message, partialsDir });
+    return createDetailedErrorMessage("Include", message, filePath, templateStr, offsetPos);
+  }
   async function processIncludeHelper(includePath, localVars = {}, templateStr, offsetPos) {
     const includeFilePath = resolvePath(includePath, partialsDir, filePath);
     if (!includeFilePath)
-      return createDetailedErrorMessage("Include", `Could not resolve path for include: ${includePath}`, filePath, templateStr, offsetPos);
+      return includeFailure(includePath, `Could not resolve path for include: ${includePath}`, templateStr, offsetPos);
     const resolvedIncludePath = path.resolve(includeFilePath);
     if (includeStack.has(resolvedIncludePath)) {
       const chain = [...includeStack, resolvedIncludePath].map((p) => path.basename(p)).join(" -> ");
-      return createDetailedErrorMessage("Include", `Circular include detected: ${chain}`, filePath, templateStr, offsetPos);
+      return includeFailure(includePath, `Circular include detected: ${chain}`, templateStr, offsetPos);
     }
     try {
       dependencies.add(includeFilePath);
@@ -529,7 +533,7 @@ export async function processIncludes(template, context, filePath, options, depe
           partialContent = await Bun.file(includeFilePath).text();
         } catch (error) {
           const errorMessage = error instanceof Error ? error.message : String(error);
-          return createDetailedErrorMessage("Include", `Error loading include file ${includePath}: ${errorMessage}`, filePath, templateStr, offsetPos);
+          return includeFailure(includePath, `Error loading include file ${includePath}: ${errorMessage}`, templateStr, offsetPos);
         }
       if (partialContent)
         partialContent = partialContent.replace(/\{\{--[\s\S]*?--\}\}/g, "");
@@ -641,7 +645,7 @@ export async function processIncludes(template, context, filePath, options, depe
       return processedContent;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      return createDetailedErrorMessage("Include", `Error processing include ${includePath}: ${errorMessage}`, filePath, templateStr, offsetPos);
+      return includeFailure(includePath, `Error processing include ${includePath}: ${errorMessage}`, templateStr, offsetPos);
     }
   }
   const includePattern = /@include\s*\(/g;

package/dist/index.d.ts

@@ -204,6 +204,9 @@ export * from './reactive-bindings';
 export * from './client-helpers';
 export * from './client-script';
 export * from './strip-literals';
+export * from './resolve-stx-targets';
+export * from './cookie-serialize';
+export * from './cli-flags';
 export * from './component-hmr';
 export * from './hydration';
 // ssg moved to stx/ssg

package/dist/index.js

@@ -113,6 +113,9 @@ export * from "./reactive-bindings.js";
 export * from "./client-helpers.js";
 export * from "./client-script.js";
 export * from "./strip-literals.js";
+export * from "./resolve-stx-targets.js";
+export * from "./cookie-serialize.js";
+export * from "./cli-flags.js";
 export * from "./component-hmr.js";
 export * from "./hydration.js";
 export * from "./ssr.js";

package/dist/page-action.d.ts

@@ -1,3 +1,4 @@
+import { type SetCookieOptions } from './cookie-serialize';
 /**
  * Parse a form submission body into a plain object.
  *
@@ -36,26 +37,7 @@ export declare function runPageAction(context: Record<string, any>, options?: Ru
  * 303 rather than 302 deliberately: it is the status that makes a browser
  * follow up with a GET, so a reload or a Back does not resubmit the form.
  */
-export declare function actionRedirectResponse(to: string): Response;
-/**
- * A page handling its own form submission (stacksjs/stx#1847).
- *
- * A page that declares `action` in its `<script server>` block receives its own
- * non-GET request. Whatever the action returns is merged into the render
- * context, so `errors` and `values` repopulate the very same template that drew
- * the form — one handler for the no-JS submit and the enhanced one, which is
- * the half of the Laravel/Remix/SvelteKit contract stx was missing.
- *
- * ## Why this is a module rather than two implementations
- *
- * It shipped in `bun-plugin/src/serve.ts` only, so a form worked under
- * `buddy dev` and silently did nothing in production — the request fell through
- * to the ordinary render and answered 200 with the pre-submit markup, which is
- * indistinguishable from the action having run and found nothing wrong. That is
- * the same dev-only-correctness shape as `stx typecheck` being stricter than
- * the editor, and this repo has been bitten repeatedly by two hand-maintained
- * copies of one rule drifting apart. One module, both servers.
- */
+export declare function actionRedirectResponse(to: string, cookies?: readonly string[]): Response;
 /**
  * Everything an action is given about the request.
  *
@@ -72,6 +54,7 @@ export declare interface PageActionContext {
 /** What running an action produced. */
 export declare interface PageActionResult {
   redirect?: string
+  cookies?: string[]
   ran: boolean
 }
 /** Request data a caller has already parsed, if it has. */
@@ -81,3 +64,10 @@ export declare interface RunPageActionOptions {
   params?: Record<string, string>
   cookies?: Record<string, string>
 }
+/**
+ * A cookie an action wants set on the response.
+ *
+ * A bare string is the whole cookie for the common case; the object form adds
+ * the attributes a session cookie needs.
+ */
+export type PageActionCookie = string | (SetCookieOptions & { value: string });

package/dist/page-action.js

@@ -1,3 +1,4 @@
+import { serializeSetCookie } from "./cookie-serialize.js";
 export async function parseFormBody(request) {
   const type = request.headers.get("content-type") || "", form = {}, put = (key, value) => {
     const existing = form[key];
@@ -46,19 +47,42 @@ export async function runPageAction(context, options = {}) {
     cookies: options.cookies ?? {}
   });
   if (result && typeof result === "object") {
-    const to = result.redirect;
+    const returned = result, cookies = serializeActionCookies(returned.cookies), to = returned.redirect;
     if (typeof to === "string" && to)
-      return { redirect: to, ran: !0 };
-    Object.assign(context, result);
+      return { redirect: to, ran: !0, ...cookies.length > 0 ? { cookies } : {} };
+    const { cookies: _cookies, redirect: _redirect, ...data } = returned;
+    Object.assign(context, data);
+    if (cookies.length > 0)
+      return { ran: !0, cookies };
   }
   return { ran: !0 };
 }
-export function actionRedirectResponse(to) {
-  return new Response(null, {
-    status: 303,
-    headers: {
-      Location: to,
-      "Cache-Control": "no-store"
+function serializeActionCookies(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return [];
+  const headers = [];
+  for (const [name, entry] of Object.entries(value)) {
+    if (!name)
+      continue;
+    if (typeof entry === "string") {
+      headers.push(serializeSetCookie(name, entry));
+      continue;
     }
+    if (entry && typeof entry === "object") {
+      const options = entry;
+      if (typeof options.value !== "string")
+        continue;
+      headers.push(serializeSetCookie(name, options.value, options));
+    }
+  }
+  return headers;
+}
+export function actionRedirectResponse(to, cookies = []) {
+  const headers = new Headers({
+    Location: to,
+    "Cache-Control": "no-store"
   });
+  for (const cookie of cookies)
+    headers.append("Set-Cookie", cookie);
+  return new Response(null, { status: 303, headers });
 }

package/dist/process.js

@@ -54,7 +54,7 @@ import { deriveLayoutGroup } from "stx-router/layout-metadata";
 import { initializeComponentClientFactories, injectComponentClientFactories } from "./component-client-factories.js";
 import { importOnce } from "./lazy-module.js";
 export { injectRouterScript } from "./runtime-injection.js";
-import { injectSignalsRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from "./runtime-injection.js";
+import { injectSignalsRuntime, injectTooltipRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from "./runtime-injection.js";
 export { processJsonDirective, processOnceDirective } from "./misc-directives.js";
 export { validateClientScript } from "./script-validation.js";
 const PARENT_PLACEHOLDER = "<!--PARENT_CONTENT_PLACEHOLDER-->";
@@ -843,6 +843,7 @@ ${runtimeScript}`);
   }
   if (!pageShipsSignalsRuntime(output) && outputNeedsSignalsRuntime(output))
     output = await injectSignalsRuntime(output, opts);
+  output = injectTooltipRuntime(output);
   if (opts.csp?.enabled && opts.csp.useNonce && typeof context.cspNonce === "string")
     output = addNonceToInlineContent(output, context.cspNonce);
   return output;

package/dist/production-server.js

@@ -165,25 +165,26 @@ export async function startProductionServer(options = {}) {
             }
           });
         try {
-          const { html, boundaries, redirect } = await hydrateTemplateStream(compiled, {
+          const { html, boundaries, redirect, cookies } = await hydrateTemplateStream(compiled, {
             params,
             request,
             method: request.method
           });
           if (redirect)
-            return actionRedirectResponse(redirect);
+            return actionRedirectResponse(redirect, cookies);
           if (boundaries && boundaries.length > 0) {
             const { renderStreamingPage, streamToResponse } = await import("./streaming.js");
             return streamToResponse(renderStreamingPage(html, boundaries, { timeoutMs: 30000 }), {
               headers: { "Cache-Control": "no-cache" }
             });
           }
-          return new Response(html, {
-            headers: {
-              "Content-Type": "text/html",
-              "Cache-Control": "no-cache"
-            }
+          const headers = new Headers({
+            "Content-Type": "text/html",
+            "Cache-Control": "no-cache"
           });
+          for (const cookie of cookies ?? [])
+            headers.append("Set-Cookie", cookie);
+          return new Response(html, { headers });
         } catch (error) {
           console.error(`[stx] Hydration error for ${pathname}:`, error);
           return new Response(compiled.html, {

package/dist/props.d.ts

@@ -1,9 +1,22 @@
 /**
  * Define component props with type safety and validation.
  *
+ * Takes an inline object type or a named `interface`/`type` — the named form is
+ * shown first because it is the one the framework scaffolds, and because every
+ * example here used to be inline. An inline literal has an implicit index
+ * signature and a named `interface` does not, so an inline-only docstring
+ * demonstrated the one spelling that could not fail (stacksjs/stx#1917).
+ *
  * @example
  * ```typescript
- * // Simple usage with types only
+ * // A named type, inline or imported — interface and type alias both work
+ * interface CardProps {
+ *   title: string
+ *   count: number
+ * }
+ * const props = defineProps<CardProps>()
+ *
+ * // Or inline
  * const props = defineProps<{
  *   title: string
  *   count: number
@@ -24,12 +37,12 @@
  * })
  * ```
  */
-export declare function defineProps<T extends Record<string, unknown>>(definitions?: PropsDefinition<T>): T;
+export declare function defineProps<T extends PropsShape>(definitions?: PropsDefinition<T>): T;
 /**
  * Define props with runtime validation.
  * Use this when you need validation errors at runtime.
  */
-export declare function definePropsWithValidation<T extends Record<string, unknown>>(definitions: PropsDefinition<T>, options?: {
+export declare function definePropsWithValidation<T extends PropsShape>(definitions: PropsDefinition<T>, options?: {
     componentName?: string
     throwOnError?: boolean
     logWarnings?: boolean
@@ -49,7 +62,7 @@ export declare function definePropsWithValidation<T extends Record<string, unkno
  * })
  * ```
  */
-export declare function withDefaults<T extends Record<string, unknown>>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
+export declare function withDefaults<T extends PropsShape>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
 /**
  * Create a prop type definition for a specific type.
  */
@@ -77,7 +90,7 @@ export declare function arrayOf<T>(_itemType: PropType<T>, options?: Omit<PropOp
 /**
  * Create a prop for object with specific shape.
  */
-export declare function shape<T extends Record<string, unknown>>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
+export declare function shape<T extends PropsShape>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
 /**
  * Process props passed to a component.
  * Called internally during component rendering.
@@ -100,7 +113,7 @@ export declare function processComponentProps(rawProps: Record<string, unknown>,
  * emit('close', undefined)
  * ```
  */
-export declare function defineEmits<E extends Record<string, unknown>>(): EmitFn<E>;
+export declare function defineEmits<E extends PropsShape>(): EmitFn<E>;
 /**
  * Expose component methods/properties to parent.
  *
@@ -113,7 +126,7 @@ export declare function defineEmits<E extends Record<string, unknown>>(): EmitFn
  * })
  * ```
  */
-export declare function defineExpose<T extends Record<string, unknown>>(exposed: T): void;
+export declare function defineExpose<T extends PropsShape>(exposed: T): void;
 /**
  * Generate TypeScript interface from prop definitions.
  * Useful for documentation and type generation.
@@ -151,6 +164,36 @@ export type PropType<T> = | StringConstructor
   | SymbolConstructor
   | { new (...args: unknown[]): T }
   | PropType<T>[];
+/**
+ * The constraint every props, emits and expose generic is bounded by.
+ *
+ * `object` rather than `Record<string, unknown>`, and the difference is not
+ * cosmetic: **a TypeScript `interface` does not satisfy an index signature.**
+ * Only a type alias gets an implicit one, so
+ *
+ *     interface CardProps { title: string }
+ *     defineProps<CardProps>()   // TS2344, TS2345
+ *     type CardProps = { title: string }
+ *     defineProps<CardProps>()   // fine
+ *
+ * differ on the keyword alone. `interface` is the form the framework scaffolds
+ * — `storage/framework/defaults/` declares props with it 44 times and with a
+ * type alias zero times — so the constraint rejected the entire scaffolded
+ * corpus (stacksjs/stx#1917).
+ *
+ * Two things hid it. Every example in the docstrings passes an inline object
+ * literal, which HAS an implicit index signature and so always passed; the
+ * error appears only once the type is named, which is the moment it is reused
+ * or exported. And apps import from `stx`, which is not a package anyone can
+ * install — the module resolved to `any`, the constraint was never enforced,
+ * and the component type-checked. Correcting the specifier in one app turned 18
+ * "Cannot find module" errors into 36 constraint errors.
+ *
+ * Named rather than written out seven times so the reason lives in one place
+ * and the sites cannot drift apart. `object` still rejects `string`, `number`
+ * and `undefined`, which is everything this constraint has to do.
+ */
+export type PropsShape = object;
 /** Props definition object */
 export type PropsDefinition<T> = {
   [K in keyof T]?: PropOptions<T[K]> | PropType<T[K]>
@@ -167,7 +210,7 @@ export type ExtractPropTypes<T extends PropsDefinition<unknown>> = {
 // eslint-disable-next-line pickier/no-unused-vars
 export type EventHandler<T = unknown> = (payload: T) => void;
 /** Emit function type */
-export type EmitFn<E extends Record<string, unknown>> = <K extends keyof E>(
+export type EmitFn<E extends PropsShape> = <K extends keyof E>(
   event: K,
   payload: E[K],
 ) => void;