@stacksjs/stx-vscode 0.2.356 → 0.2.358

package/README.md

@@ -28,6 +28,16 @@ The static half has to be in your extension's manifest, because VS Code reads gr
 
 `vscode`, `prettier` and `@stacksjs/ts-css` are imported, not bundled: bundle the library into your extension.
 
+## Type checking `.stx` files
+
+The TypeScript server plugin ships too, as a complete package in `dist/typescript-plugin/` (`@stacksjs/stx-typescript-plugin/...` is exported as `@stacksjs/stx-vscode/typescript-plugin/*`). To type-check `.stx` files in the editor:
+
+1. Declare `typescriptServerPlugins` from `contributes.json` in your manifest.
+2. Put the package where tsserver looks for it: tsserver loads a plugin only by package name, from `<your extension>/node_modules/@stacksjs/stx-typescript-plugin`. If you package with `vsce --no-dependencies`, which leaves `node_modules` out, ship the directory elsewhere in the VSIX and add a two-file forwarder package under `node_modules` after `vsce` writes it, as the Stacks extension does.
+3. Call `configureTypeScriptPlugin(vscode, context.subscriptions)` in `activate`. It starts VS Code's TypeScript extension, which does not activate on `stx` by itself, and forwards `stxTypescriptPlugin.enabled` to the plugin.
+
+The stx extension contributes the same plugin under the same name. With both extensions installed, tsserver loads it once per contribution, and the plugin decorates each project only the first time.
+
 ## License
 
 MIT

package/dist/contributes.json

@@ -166,5 +166,14 @@
         "markdownDescription": "Pixels per `rem` for the px values utility-class hovers show next to `rem` values. `0` hides them. Replaces `css.remToPxRatio`, which is still read when this is not set."
       }
     }
-  }
+  },
+  "typescriptServerPlugins": [
+    {
+      "name": "@stacksjs/stx-typescript-plugin",
+      "enableForWorkspaceTypeScriptVersions": true,
+      "languages": [
+        "stx"
+      ]
+    }
+  ]
 }

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Written by hand rather than generated: the implementation (packages/vscode/src)
  * is typed against `@types/vscode`, and generating from it would make every
- * consumer install those types to read four functions.
+ * consumer install those types to read a handful of functions.
  */
 
 /** The marketplace ID of the standalone stx extension. */
@@ -46,3 +46,35 @@ export interface StxLanguageOptions {
 export declare function activateStxLanguage(context: StxExtensionContext, options: StxLanguageOptions): Promise<void>
 
 export declare function deactivateStxLanguage(): void
+
+/** The name the TypeScript server plugin is contributed and configured under. */
+export declare const TS_PLUGIN_NAME: '@stacksjs/stx-typescript-plugin'
+
+/** The settings section the plugin reads (`stxTypescriptPlugin.enabled`). */
+export declare const TS_PLUGIN_SETTINGS: 'stxTypescriptPlugin'
+
+/** VS Code's built-in TypeScript extension. */
+export declare const TYPESCRIPT_EXTENSION_ID: 'vscode.typescript-language-features'
+
+/** The part of the `vscode` API `configureTypeScriptPlugin` uses. */
+export interface TsPluginHostApi {
+  extensions: {
+    getExtension: (id: string) => { isActive: boolean, exports: unknown, activate: () => PromiseLike<unknown> } | undefined
+  }
+  workspace: {
+    getConfiguration: (section: string) => { get: <T>(key: string, fallback: T) => T }
+    onDidChangeConfiguration: (listener: (event: { affectsConfiguration: (section: string) => boolean }) => void) => { dispose: () => void }
+  }
+}
+
+/**
+ * Start VS Code's TypeScript extension, which does not activate on `stx` by
+ * itself, and forward `stxTypescriptPlugin.enabled` to the plugin now and on
+ * every change. Resolves to whether the TypeScript API was reached.
+ *
+ * Pass the `vscode` module as `api`. Call it from any extension that
+ * contributes the plugin (`typescriptServerPlugins` in `contributes.json`);
+ * with the stx extension installed too, both contribute and configure it and
+ * the plugin decorates each project once.
+ */
+export declare function configureTypeScriptPlugin(api: TsPluginHostApi, subscriptions: Array<{ dispose: () => void }>): Promise<boolean>

package/dist/index.js

@@ -7012,6 +7012,7 @@ export {
   createCssCompletionProvider,
   createCompletionProvider,
   createCodeActionsProvider,
+  configureTypeScriptPlugin,
   addRemToPxComment,
   activateStxLanguage,
   activateCss,
@@ -7020,6 +7021,9 @@ export {
   TransitionType,
   TransitionEase,
   TransitionDirection,
+  TYPESCRIPT_EXTENSION_ID,
+  TS_PLUGIN_SETTINGS,
+  TS_PLUGIN_NAME,
   STX_EXTENSION_ID,
   STACKS_EXTENSION_ID,
   PropsTypeExtractor,

package/dist/typescript-plugin/index.js

@@ -0,0 +1,3 @@
+const path = require('path')
+const init = require('./typescript-stx-plugin.js')
+module.exports = modules => init(modules, { declarationsDir: path.join(__dirname, './types') })

package/dist/typescript-plugin/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@stacksjs/stx-typescript-plugin",
+  "version": "0.2.358",
+  "private": true,
+  "main": "index.js"
+}

package/dist/typescript-plugin/types/stx-module.d.ts

@@ -0,0 +1,154 @@
+/// <reference path="./stx.d.ts" />
+
+/**
+ * The `stx` module, as a `.stx` script block sees it.
+ *
+ * `stx` is a VIRTUAL specifier. No package by that name is installed in an app,
+ * and `import { … } from 'stx'` works only because both script paths intercept
+ * it: a client block's import is stripped and its names destructured off
+ * `window.stx`, and a server block's names are handed in by the engine as
+ * parameters. So what this module exports is exactly what those two paths bind,
+ * and nothing else from `@stacksjs/stx` (see src/stx-module-imports.ts):
+ *
+ *  - every name destructured off `window.stx` (STX_RUNTIME_GLOBALS), which a
+ *    server block also receives where the engine binds it, and
+ *  - the stx API names only the server engine binds, marked below.
+ *
+ * Each value is typed by the ambient global of the same name in `stx.d.ts`, so
+ * an imported `state` is exactly the auto-imported one; the module adds no
+ * second copy of any signature to drift.
+ *
+ * This file is NOT referenced from the package's types entry, on purpose. The
+ * specifier is virtual only inside a `.stx` block; a `.ts` file importing from
+ * `stx` has a real import that does not resolve. `stx typecheck` and the editor
+ * plugin add it to the programs they build for `.stx` files.
+ *
+ * Which block kind gets which name is checked separately, because one
+ * declaration cannot say it: `stxImportDiagnostics` reports a server-only name
+ * imported into a client block and the reverse.
+ *
+ * test/stx-module-declaration.test.ts keeps this list equal to the runtime's.
+ */
+declare module 'stx' {
+  export const $props: Record<string, any> // <script server> only
+  export const batch: typeof globalThis.batch
+  export const clearServerData: typeof globalThis.clearServerData
+  export const computed: typeof globalThis.computed
+  export const configureFetch: typeof globalThis.configureFetch
+  export const defineClientPayload: (payload: Record<string, unknown>) => void // <script server> only
+  export const defineEmits: typeof globalThis.defineEmits
+  export const defineExpose: typeof globalThis.defineExpose
+  export const definePageMeta: typeof globalThis.definePageMeta
+  export const defineProps: typeof globalThis.defineProps
+  export const defineSlots: typeof globalThis.defineSlots
+  export const defineStore: typeof globalThis.defineStore
+  export const derived: typeof globalThis.derived
+  export const effect: typeof globalThis.effect
+  export const goBack: typeof globalThis.goBack
+  export const goForward: typeof globalThis.goForward
+  export const inject: typeof globalThis.inject
+  export const invalidateRoute: typeof globalThis.invalidateRoute
+  export const isDerived: typeof globalThis.isDerived
+  export const isSignal: typeof globalThis.isSignal
+  export const navigate: typeof globalThis.navigate
+  export const nextTick: typeof globalThis.nextTick
+  export const notFound: (status?: number) => void // <script server> only
+  export const onBeforeMount: typeof globalThis.onBeforeMount
+  export const onBeforeUnmount: typeof globalThis.onBeforeUnmount
+  export const onDestroy: typeof globalThis.onDestroy
+  export const onMount: typeof globalThis.onMount
+  export const onMounted: typeof globalThis.onMounted
+  export const onUnmounted: typeof globalThis.onUnmounted
+  export const params: Record<string, string> // <script server> only
+  export const peek: typeof globalThis.peek
+  export const props: Record<string, any> // <script server> only
+  export const provide: typeof globalThis.provide
+  export const reactive: typeof globalThis.reactive
+  export const ref: typeof globalThis.ref
+  export const refresh: typeof globalThis.refresh
+  export const registerStoresClient: typeof globalThis.registerStoresClient
+  export const setResponseHeader: (name: string, value: string) => void // <script server> only
+  export const setResponseStatus: (status: number) => void // <script server> only
+  export const setRouteParams: typeof globalThis.setRouteParams
+  export const state: typeof globalThis.state
+  export const untrack: typeof globalThis.untrack
+  export const useAsync: typeof globalThis.useAsync
+  export const useClickOutside: typeof globalThis.useClickOutside
+  export const useColorMode: typeof globalThis.useColorMode
+  export const useCookie: typeof globalThis.useCookie
+  export const useCounter: typeof globalThis.useCounter
+  export const useDark: typeof globalThis.useDark
+  export const useDebounce: typeof globalThis.useDebounce
+  export const useDebouncedValue: typeof globalThis.useDebouncedValue
+  export const useDocumentVisibility: typeof globalThis.useDocumentVisibility
+  export const useEventListener: typeof globalThis.useEventListener
+  export const useFetch: typeof globalThis.useFetch
+  export const useFocus: typeof globalThis.useFocus
+  export const useHead: typeof globalThis.useHead
+  export const useId: typeof globalThis.useId
+  export const useInterval: typeof globalThis.useInterval
+  export const useLocalStorage: typeof globalThis.useLocalStorage
+  export const useMediaQuery: typeof globalThis.useMediaQuery
+  export const useModel: typeof globalThis.useModel
+  export const useMutation: typeof globalThis.useMutation
+  export const useOptimistic: typeof globalThis.useOptimistic
+  export const usePreferredContrast: typeof globalThis.usePreferredContrast
+  export const usePreferredDark: typeof globalThis.usePreferredDark
+  export const usePreferredLight: typeof globalThis.usePreferredLight
+  export const usePreferredReducedMotion: typeof globalThis.usePreferredReducedMotion
+  export const useQuery: typeof globalThis.useQuery
+  export const useReactiveProp: typeof globalThis.useReactiveProp
+  export const useRef: typeof globalThis.useRef
+  export const useRoute: typeof globalThis.useRoute
+  export const useRouteParam: typeof globalThis.useRouteParam
+  export const useRouteParams: typeof globalThis.useRouteParams
+  export const useRouter: () => { push: (to: unknown) => void, replace: (to: unknown) => void, back: () => void, forward: () => void, go: (n: number) => void } // <script server> only
+  export const useRuntimeConfig: () => Readonly<Record<string, any>> // <script server> only
+  export const useScrollLock: typeof globalThis.useScrollLock
+  export const useSearchParams: typeof globalThis.useSearchParams
+  export const useSeoMeta: typeof globalThis.useSeoMeta
+  export const useServerData: typeof globalThis.useServerData // <script server> only
+  export const useServerRuntimeConfig: () => Readonly<{ public: Record<string, any>, private: Record<string, any> }> // <script server> only
+  export const useSessionStorage: typeof globalThis.useSessionStorage
+  export const useSlots: typeof globalThis.useSlots
+  export const useStore: typeof globalThis.useStore
+  export const useThrottle: typeof globalThis.useThrottle
+  export const useTimeout: typeof globalThis.useTimeout
+  export const useToggle: typeof globalThis.useToggle
+  export const useWebSocket: typeof globalThis.useWebSocket
+  export const watch: typeof globalThis.watch
+  export const watchEffect: typeof globalThis.watchEffect
+  export const watchMultiple: typeof globalThis.watchMultiple
+  export const withDefaults: typeof globalThis.withDefaults
+
+  export type StxSignal<T> = globalThis.StxSignal<T>
+  export type StxDerivedSignal<T> = globalThis.StxDerivedSignal<T>
+  export type StxRef<T> = globalThis.StxRef<T>
+  export type StxCleanup = globalThis.StxCleanup
+  export type StxModelOptions<T> = globalThis.StxModelOptions<T>
+  export type StxModelSignal<T> = globalThis.StxModelSignal<T>
+  export type StxTemplateRef<T> = globalThis.StxTemplateRef<T>
+  export type StxNavigateOptions = globalThis.StxNavigateOptions
+  export type StxSearchParamsCommitOptions = globalThis.StxSearchParamsCommitOptions
+  export type StxRefetchOptions = globalThis.StxRefetchOptions
+  export type StxFetchResult<T> = globalThis.StxFetchResult<T>
+  export type StxQueryResult<T> = globalThis.StxQueryResult<T>
+  export type StxMutationResult<T> = globalThis.StxMutationResult<T>
+  export type StxFetchRequestContext = globalThis.StxFetchRequestContext
+  export type StxFetchResponseContext = globalThis.StxFetchResponseContext
+  export type StxFetchErrorContext = globalThis.StxFetchErrorContext
+  export type StxEventListenerOptions = globalThis.StxEventListenerOptions
+  export type StxIntervalOptions = globalThis.StxIntervalOptions
+  export type StxIntervalControls = globalThis.StxIntervalControls
+  export type StxCookieOptions = globalThis.StxCookieOptions
+  export type StxColorModeOptions = globalThis.StxColorModeOptions
+  export type StxHeadConfig = globalThis.StxHeadConfig
+  export type StxSeoMetaConfig = globalThis.StxSeoMetaConfig
+  export type StxToastOptions = globalThis.StxToastOptions
+  export type StxToast = globalThis.StxToast
+  export type StxModal = globalThis.StxModal
+  export type StxDrawer = globalThis.StxDrawer
+  export type StxDialogOptions = globalThis.StxDialogOptions
+  export type StxStorePersistOptions = globalThis.StxStorePersistOptions
+  export type StxStoreOptions = globalThis.StxStoreOptions
+}