@stacksjs/stx 0.2.189 → 0.2.190

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/stx.d.ts CHANGED
@@ -355,15 +355,46 @@ declare function useFocus(_target: HTMLElement | StxRef<HTMLElement | null> | st
355
355
  declare function useDebounce<T extends (..._args: any[]) => any>(_fn: T, _delay: number): T
356
356
  declare function useDebouncedValue<T>(_value: StxSignal<T>, _delay: number): StxSignal<T>
357
357
  declare function useThrottle<T extends (..._args: any[]) => any>(_fn: T, _delay: number): T
358
- declare function useInterval(_fn: () => void, _ms: number, _options?: { immediate?: boolean }): {
359
- start: () => void
360
- stop: () => void
361
- isActive: StxSignal<boolean>
358
+ interface StxIntervalOptions {
359
+ /** Tick once on start/resume instead of waiting out the first interval. */
360
+ immediate?: boolean
361
+ /** Gate ticks. `false`, or a function returning false, skips them entirely. */
362
+ enabled?: boolean | (() => boolean)
363
+ /** Skip ticks while `document.hidden`. */
364
+ whileVisible?: boolean
365
+ }
366
+
367
+ interface StxIntervalControls {
368
+ /**
369
+ * Ticks elapsed. A plain number — read it, do not call it. It is not a
370
+ * signal and an `effect` cannot track it; use `subscribe` to react.
371
+ */
372
+ readonly counter: number
373
+ pause: () => void
374
+ resume: () => void
375
+ reset: () => void
376
+ /** Runs on each tick with the new count. Returns an unsubscribe. */
377
+ subscribe: (_fn: (_count: number) => void) => () => void
362
378
  }
363
- declare function useTimeout(_fn: () => void, _ms: number): {
379
+
380
+ /**
381
+ * Interval with controls. Both call forms work:
382
+ * `useInterval(1000)` for the counter, `useInterval(fn, 1000)` to run something.
383
+ *
384
+ * There is deliberately no `start`/`stop`/`isActive` here. A declaration of that
385
+ * shape shipped for some time and nothing implemented it, so calls against it
386
+ * typechecked clean and threw `poll.start is not a function` on mount (#1941).
387
+ * `resume`/`pause` are the real names.
388
+ */
389
+ declare function useInterval(_interval?: number, _options?: StxIntervalOptions): StxIntervalControls
390
+ declare function useInterval(_fn: (_count: number) => void, _ms?: number, _options?: StxIntervalOptions): StxIntervalControls
391
+ declare function useInterval(_fn: (_count: number) => void, _options?: StxIntervalOptions): StxIntervalControls
392
+ declare function useTimeout(_fn: () => void, _ms?: number): {
393
+ /** Plain boolean, not a signal. Use `subscribe` to react to it. */
394
+ readonly isPending: boolean
364
395
  start: () => void
365
396
  stop: () => void
366
- isPending: StxSignal<boolean>
397
+ subscribe: (_fn: (_pending: boolean) => void) => () => void
367
398
  }
368
399
  declare function nextTick(_fn?: () => void): Promise<void>
369
400
 
package/dist/typecheck.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
2
  import path from "node:path";
3
+ import { listComposableModules } from "./composable-loader.js";
3
4
  import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
4
5
  import { stateDir } from "./state-dir.js";
5
6
  import {
@@ -40,6 +41,50 @@ function virtualStxModuleDeclaration(files) {
40
41
  ].join(`
41
42
  `);
42
43
  }
44
+ const WINDOW_OWNED_NAMES = new Set([
45
+ "name",
46
+ "status",
47
+ "length",
48
+ "location",
49
+ "history",
50
+ "origin",
51
+ "closed",
52
+ "close",
53
+ "open",
54
+ "focus",
55
+ "blur",
56
+ "print",
57
+ "scroll",
58
+ "scrollTo",
59
+ "scrollBy",
60
+ "stop",
61
+ "top",
62
+ "parent",
63
+ "self",
64
+ "frames",
65
+ "event",
66
+ "external",
67
+ "menubar",
68
+ "toolbar"
69
+ ]);
70
+ function composableGlobalDeclarations(modules) {
71
+ if (modules.length === 0)
72
+ return "";
73
+ const lines = ["// Generated \u2014 the composables the runtime publishes as bare globals."], taken = new Set(STX_RUNTIME_GLOBALS), reExports = [];
74
+ for (const { file, names } of modules) {
75
+ const specifier = JSON.stringify(file.replace(/\\/g, "/").replace(/\.ts$/, ""));
76
+ reExports.push(` export * from ${specifier}`);
77
+ for (const name of names) {
78
+ if (taken.has(name) || WINDOW_OWNED_NAMES.has(name))
79
+ continue;
80
+ taken.add(name);
81
+ lines.push(`declare const ${name}: typeof import(${specifier})[${JSON.stringify(name)}]`);
82
+ }
83
+ }
84
+ lines.push("declare module '@composables' {", ...reExports, "}");
85
+ return lines.join(`
86
+ `);
87
+ }
43
88
  export function virtualPathFor(filePath, kind, index) {
44
89
  return `${filePath}.__stx_${kind}${index}.ts`;
45
90
  }
@@ -188,7 +233,8 @@ export async function typecheckStxFiles(files, options = {}) {
188
233
  "// Generated \u2014 the context serve.ts injects into <script server> blocks.",
189
234
  serverContextDeclarations(),
190
235
  ...runtimeTypes ? [] : ["declare const window: any", ...STX_RUNTIME_GLOBALS.map((name) => `declare const ${name}: any`)],
191
- virtualStxModuleDeclaration(files)
236
+ virtualStxModuleDeclaration(files),
237
+ composableGlobalDeclarations(await listComposableModules())
192
238
  ].filter(Boolean).join(`
193
239
  `), workDir = `${stateDir()}/typecheck`;
194
240
  await Bun.$`rm -rf ${workDir}`.quiet().nothrow();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@stacksjs/stx",
3
3
  "type": "module",
4
- "version": "0.2.189",
4
+ "version": "0.2.190",
5
5
  "description": "A performant UI Framework. Powered by Bun.",
6
6
  "author": "Chris Breuer <chris@stacksjs.org>",
7
7
  "license": "MIT",
@@ -117,12 +117,12 @@
117
117
  "dependencies": {
118
118
  "@cwcss/crosswind": "^0.2.14",
119
119
  "@stacksjs/clapp": "^0.2.0",
120
- "@stacksjs/desktop": "0.2.189",
121
- "@stacksjs/sanitizer": "0.2.189",
120
+ "@stacksjs/desktop": "0.2.190",
121
+ "@stacksjs/sanitizer": "0.2.190",
122
122
  "@stacksjs/ts-i18n": "^0.1.11",
123
- "bun-plugin-stx": "0.2.189",
123
+ "bun-plugin-stx": "0.2.190",
124
124
  "bunfig": "^0.15.17",
125
- "stx-router": "0.2.189",
125
+ "stx-router": "0.2.190",
126
126
  "ts-broadcasting": "^0.0.9",
127
127
  "ts-images": "^0.2.11",
128
128
  "ts-syntax-highlighter": "^0.2.1"
package/stx.d.ts CHANGED
@@ -355,15 +355,46 @@ declare function useFocus(_target: HTMLElement | StxRef<HTMLElement | null> | st
355
355
  declare function useDebounce<T extends (..._args: any[]) => any>(_fn: T, _delay: number): T
356
356
  declare function useDebouncedValue<T>(_value: StxSignal<T>, _delay: number): StxSignal<T>
357
357
  declare function useThrottle<T extends (..._args: any[]) => any>(_fn: T, _delay: number): T
358
- declare function useInterval(_fn: () => void, _ms: number, _options?: { immediate?: boolean }): {
359
- start: () => void
360
- stop: () => void
361
- isActive: StxSignal<boolean>
358
+ interface StxIntervalOptions {
359
+ /** Tick once on start/resume instead of waiting out the first interval. */
360
+ immediate?: boolean
361
+ /** Gate ticks. `false`, or a function returning false, skips them entirely. */
362
+ enabled?: boolean | (() => boolean)
363
+ /** Skip ticks while `document.hidden`. */
364
+ whileVisible?: boolean
365
+ }
366
+
367
+ interface StxIntervalControls {
368
+ /**
369
+ * Ticks elapsed. A plain number — read it, do not call it. It is not a
370
+ * signal and an `effect` cannot track it; use `subscribe` to react.
371
+ */
372
+ readonly counter: number
373
+ pause: () => void
374
+ resume: () => void
375
+ reset: () => void
376
+ /** Runs on each tick with the new count. Returns an unsubscribe. */
377
+ subscribe: (_fn: (_count: number) => void) => () => void
362
378
  }
363
- declare function useTimeout(_fn: () => void, _ms: number): {
379
+
380
+ /**
381
+ * Interval with controls. Both call forms work:
382
+ * `useInterval(1000)` for the counter, `useInterval(fn, 1000)` to run something.
383
+ *
384
+ * There is deliberately no `start`/`stop`/`isActive` here. A declaration of that
385
+ * shape shipped for some time and nothing implemented it, so calls against it
386
+ * typechecked clean and threw `poll.start is not a function` on mount (#1941).
387
+ * `resume`/`pause` are the real names.
388
+ */
389
+ declare function useInterval(_interval?: number, _options?: StxIntervalOptions): StxIntervalControls
390
+ declare function useInterval(_fn: (_count: number) => void, _ms?: number, _options?: StxIntervalOptions): StxIntervalControls
391
+ declare function useInterval(_fn: (_count: number) => void, _options?: StxIntervalOptions): StxIntervalControls
392
+ declare function useTimeout(_fn: () => void, _ms?: number): {
393
+ /** Plain boolean, not a signal. Use `subscribe` to react to it. */
394
+ readonly isPending: boolean
364
395
  start: () => void
365
396
  stop: () => void
366
- isPending: StxSignal<boolean>
397
+ subscribe: (_fn: (_pending: boolean) => void) => () => void
367
398
  }
368
399
  declare function nextTick(_fn?: () => void): Promise<void>
369
400