@stacksjs/stx 0.2.155 → 0.2.157

package/dist/web-components.d.ts

@@ -3,6 +3,72 @@ import type { StxOptions } from './types';
  * Builds web components from stx components
  */
 export declare function buildWebComponents(options: StxOptions, dependencies: Set<string>): Promise<string[]>;
+/**
+ * Property definition for reactive web components
+ */
+export interface ReactivePropertyDefinition {
+    /** Property type for serialization/deserialization */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Default value */
+    default?: unknown;
+    /** Whether property reflects to attribute */
+    reflect?: boolean;
+    /** Custom attribute name (defaults to kebab-case of property name) */
+    attribute?: string | false;
+    /** Observer function name to call when property changes */
+    observer?: string;
+    /** Whether property changes should trigger re-render */
+    render?: boolean;
+}
+/**
+ * Reactive web component configuration
+ */
+export interface ReactiveWebComponentConfig {
+    /** Component class name */
+    name: string;
+    /** Custom element tag name */
+    tag: string;
+    /** Base element to extend */
+    baseElement?: string;
+    /** Component template HTML */
+    template: string;
+    /** Component styles (CSS) */
+    styles?: string;
+    /** Whether to use Shadow DOM */
+    shadowDOM?: boolean;
+    /** Reactive property definitions */
+    properties?: Record<string, ReactivePropertyDefinition>;
+    /** Lifecycle hooks to include */
+    lifecycle?: {
+        connected?: string;
+        disconnected?: string;
+        adopted?: string;
+        attributeChanged?: string;
+    };
+    /** Event handlers */
+    events?: Record<string, string>;
+    /** Methods to include in the component */
+    methods?: Record<string, string>;
+    /** Initial state */
+    state?: Record<string, unknown>;
+}
+/**
+ * CSS scoping strategy
+ */
+export type CssScopingStrategy = 'shadow' | 'prefix' | 'attribute' | 'bem';
+/**
+ * CSS scoping configuration
+ */
+export interface CssScopingConfig {
+    /** Scoping strategy to use */
+    strategy: CssScopingStrategy;
+    /** Prefix for class-based scoping (strategy: 'prefix') */
+    prefix?: string;
+    /** Attribute name for attribute-based scoping (strategy: 'attribute') */
+    attributeName?: string;
+    /** Whether to preserve original class names */
+    preserveOriginal?: boolean;
+}
 /**
  * Generate a unique scope ID for a component
  */
@@ -50,7 +116,10 @@ export declare function getScopeAttribute(componentTag: string, config?: Partial
  * @param config - Scoping configuration
  * @returns Object with scoped HTML and extracted scoped CSS
  */
-export declare function extractAndScopeStyles(html: string, componentTag: string, config?: Partial<CssScopingConfig>): { html: string, css: string };
+export declare function extractAndScopeStyles(html: string, componentTag: string, config?: Partial<CssScopingConfig>): {
+    html: string;
+    css: string;
+};
 /**
  * Generate a reactive web component with full lifecycle management.
  *
@@ -117,6 +186,17 @@ export declare function generateReactiveMixin(): string;
  * @returns JavaScript runtime code
  */
 export declare function generateReactiveRuntime(): string;
+/**
+ * Parsed SFC web component structure
+ */
+export interface ParsedSFCComponent {
+    tag: string;
+    props: string[];
+    template: string;
+    styles: string;
+    script: string;
+    shadowDOM: boolean;
+}
 /**
  * Parse an SFC-style web component file
  *
@@ -170,61 +250,4 @@ export declare function generateSFCWebComponent(parsed: ParsedSFCComponent): str
  * </style>
  * ```
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function webComponentDirectiveHandler(content: string, params: string[], context: Record<string, any>, filePath: string): Promise<string>;
-/**
- * Property definition for reactive web components
- */
-export declare interface ReactivePropertyDefinition {
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array'
-  default?: unknown
-  reflect?: boolean
-  attribute?: string | false
-  observer?: string
-  render?: boolean
-}
-/**
- * Reactive web component configuration
- */
-export declare interface ReactiveWebComponentConfig {
-  name: string
-  tag: string
-  baseElement?: string
-  template: string
-  styles?: string
-  shadowDOM?: boolean
-  properties?: Record<string, ReactivePropertyDefinition>
-  lifecycle?: {
-    connected?: string
-    disconnected?: string
-    adopted?: string
-    attributeChanged?: string
-  }
-  events?: Record<string, string>
-  methods?: Record<string, string>
-  state?: Record<string, unknown>
-}
-/**
- * CSS scoping configuration
- */
-export declare interface CssScopingConfig {
-  strategy: CssScopingStrategy
-  prefix?: string
-  attributeName?: string
-  preserveOriginal?: boolean
-}
-/**
- * Parsed SFC web component structure
- */
-export declare interface ParsedSFCComponent {
-  tag: string
-  props: string[]
-  template: string
-  styles: string
-  script: string
-  shadowDOM: boolean
-}
-/**
- * CSS scoping strategy
- */
-export type CssScopingStrategy = 'shadow' | 'prefix' | 'attribute' | 'bem';

package/dist/x-element.d.ts

@@ -1,4 +1,3 @@
-/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * x-element: Lightweight two-way binding for STX
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.155",
+  "version": "0.2.157",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -117,12 +117,12 @@
   "dependencies": {
     "@cwcss/crosswind": "^0.2.14",
     "@stacksjs/clapp": "^0.2.0",
-    "@stacksjs/desktop": "0.2.155",
-    "@stacksjs/sanitizer": "0.2.155",
+    "@stacksjs/desktop": "0.2.157",
+    "@stacksjs/sanitizer": "0.2.157",
     "@stacksjs/ts-i18n": "^0.1.11",
-    "bun-plugin-stx": "0.2.155",
+    "bun-plugin-stx": "0.2.157",
     "bunfig": "^0.15.17",
-    "stx-router": "0.2.155",
+    "stx-router": "0.2.157",
     "ts-broadcasting": "^0.0.9",
     "ts-images": "^0.1.9",
     "ts-syntax-highlighter": "^0.2.1"

package/stx.d.ts

@@ -124,9 +124,24 @@ interface StxNavigateOptions {
  * shape that actually shipped — but keeping it out of the type means nothing
  * that type-checks today changes meaning (#1807).
  */
-declare function navigate(_url: string, _options?: StxNavigateOptions): void
+declare function navigate<T extends string>(
+  _url: T & import('@stacksjs/stx').CheckHref<T>,
+  _options?: StxNavigateOptions,
+): void
 declare function goBack(): void
 declare function goForward(): void
+
+/**
+ * Re-run the current route against the server and swap the result, without a
+ * document load. Use after a mutation that changed server-rendered content.
+ */
+declare function refresh(): Promise<boolean>
+
+/**
+ * Expire one cached route so the next visit re-fetches it. Defaults to the
+ * current path.
+ */
+declare function invalidateRoute(_url?: string): void
 declare function useRoute(): {
   path: string
   params: Record<string, string>
@@ -134,6 +149,17 @@ declare function useRoute(): {
   hash: string
 }
 declare function setRouteParams(_params: Record<string, string>): void
+
+/**
+ * Reactive access to the current route's dynamic segments.
+ *
+ * Published on `window.stx` by 5daaba1f9b but never added to the auto-imported
+ * list, so it was reachable only as `window.stx.useRouteParams()` — exactly the
+ * authoring-surface gap in #1846.
+ */
+declare function useRouteParams(): StxSignal<Record<string, string>>
+/** One dynamic segment, as a signal. */
+declare function useRouteParam(_name: string, _defaultValue?: string): StxSignal<string>
 /** How a search-param mutation is written to session history (#1825). */
 interface StxSearchParamsCommitOptions {
   /** Replace the current history entry instead of pushing a new one. */
@@ -190,6 +216,52 @@ interface StxMutationResult<T> {
 declare function useFetch<T = any>(_url: string, _options?: any): StxQueryResult<T>
 declare function useQuery<T = any>(_url: string, _options?: any): StxQueryResult<T>
 declare function useMutation<T = any>(_url: string, _options?: any): StxMutationResult<T>
+
+/** Context handed to a request interceptor. Mutate it; the return is ignored. */
+interface StxFetchRequestContext {
+  /** Which primitive made the call: 'useFetch' | 'useQuery' | 'useMutation'. */
+  source: string
+  /** Reassignable, so a hook can prefix a baseURL. */
+  url: string
+  /** `headers` is normalised to an object before the hook runs. */
+  options: RequestInit & { headers: Record<string, string> }
+}
+
+/** Context handed to a response interceptor. */
+interface StxFetchResponseContext extends StxFetchRequestContext {
+  response: Response
+}
+
+/**
+ * Context handed to an error interceptor. `response` is the non-ok Response, or
+ * null when the fetch itself threw (a network failure); `error` is set only in
+ * the latter case.
+ */
+interface StxFetchErrorContext extends StxFetchRequestContext {
+  response: Response | null
+  error: Error | null
+}
+
+/**
+ * Install request/response interceptors for every stx data primitive.
+ *
+ * All three funnel through one internal fetch, so a single pair of hooks
+ * carries an auth header or observes a 401 across `useFetch`, `useQuery` and
+ * `useMutation`. Calling this again REPLACES the hooks rather than adding to
+ * them, so a re-evaluated module cannot install the same interceptor twice.
+ *
+ * `onResponseError` fires for a non-ok response and for a thrown fetch. Return
+ * a Response to replace the failed one — the shape a 401 -> refresh -> retry
+ * takes: refresh the token, re-issue the request with a plain `fetch()` (not
+ * this data layer, so it does not re-enter the hook), and return that Response.
+ * Return nothing to let the original error stand.
+ */
+declare function configureFetch(_config: {
+  onRequest?: (_ctx: StxFetchRequestContext) => void | Promise<void>
+  onResponse?: (_ctx: StxFetchResponseContext) => void | Promise<void>
+  onResponseError?: (_ctx: StxFetchErrorContext) => void | Response | Promise<void | Response>
+}): void
+
 declare function useOptimistic<T = any, A = any>(
   _base: StxSignal<T> | (() => T) | T,
   _reducer: (_current: T, _action: A) => T,
@@ -591,14 +663,19 @@ interface StxRuntimeRegistry {
   useRef: typeof useRef
   useQuery: typeof useQuery
   useMutation: typeof useMutation
+  configureFetch: typeof configureFetch
   useOptimistic: typeof useOptimistic
 
   // Routing
   navigate: typeof navigate
   goBack: typeof goBack
   goForward: typeof goForward
+  refresh: typeof refresh
+  invalidateRoute: typeof invalidateRoute
   useRoute: typeof useRoute
   setRouteParams: typeof setRouteParams
+  useRouteParams: typeof useRouteParams
+  useRouteParam: typeof useRouteParam
   useSearchParams: typeof useSearchParams
 
   // Composition