@qds.dev/base 0.11.2 → 0.13.0

package/lib/helpers/create-getter.d.ts

@@ -0,0 +1,30 @@
+import type { ComputedSignal, Signal } from "@qwik.dev/core";
+type SignalFields<T> = {
+    [K in keyof T]: T[K] extends Signal ? K : never;
+}[keyof T];
+type UnwrapSignal<T> = T extends Signal<infer V> ? V : T;
+/**
+ * Creates a type-safe getter factory for exposing component context state to consumers.
+ *
+ * Qwik's context system requires `useContext()` inside a `component$()` that is a
+ * descendant of the provider. Consumers can't read component state from the parent scope.
+ * The QDS UI plugin (`qds()`) solves this by detecting `get`-prefixed namespace properties
+ * in JSX and generating `component$()` wrappers at build time.
+ *
+ * This function creates proxy placeholders typed against the context. The plugin rewrites
+ * all references before runtime — the proxy only triggers if the plugin is missing.
+ *
+ * @example
+ * ```ts
+ * // select/index.ts
+ * const context = createContextProxy<SelectContext>();
+ *
+ * export const getIsOpen = context("isOpen");
+ * export const getSelectedValues = context("selectedValues");
+ *
+ * // Consumer JSX — plugin transforms this into a generated component$():
+ * <select.trigger>{select.getIsOpen.value ? "Open" : "Closed"}</select.trigger>
+ * ```
+ */
+export declare function createContextProxy<TContext>(): <TField extends SignalFields<TContext>>(field: TField) => ComputedSignal<UnwrapSignal<TContext[TField]>>;
+export {};

package/lib/helpers/create-getter.qwik.mjs

@@ -0,0 +1,33 @@
+//#region src/helpers/create-getter.ts
+/**
+* Creates a type-safe getter factory for exposing component context state to consumers.
+*
+* Qwik's context system requires `useContext()` inside a `component$()` that is a
+* descendant of the provider. Consumers can't read component state from the parent scope.
+* The QDS UI plugin (`qds()`) solves this by detecting `get`-prefixed namespace properties
+* in JSX and generating `component$()` wrappers at build time.
+*
+* This function creates proxy placeholders typed against the context. The plugin rewrites
+* all references before runtime — the proxy only triggers if the plugin is missing.
+*
+* @example
+* ```ts
+* // select/index.ts
+* const context = createContextProxy<SelectContext>();
+*
+* export const getIsOpen = context("isOpen");
+* export const getSelectedValues = context("selectedValues");
+*
+* // Consumer JSX — plugin transforms this into a generated component$():
+* <select.trigger>{select.getIsOpen.value ? "Open" : "Closed"}</select.trigger>
+* ```
+*/ function createContextProxy() {
+	return (field) => {
+		return new Proxy({}, { get() {
+			throw new Error(`We tried to grab and create context for ${String(field)} in the top level, using the getX pattern, but it appears the qds vite plugin did not transform it correct (or is missing). Add qds() to the start of the plugins array in your Vite config.`);
+		} });
+	};
+}
+
+//#endregion
+export { createContextProxy };

package/lib/helpers/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./aria-ids";
+export { createContextProxy } from "./create-getter";
 export * from "./cache";
 export * from "./hash";
 export * from "./id-list";

package/lib/helpers/index.qwik.mjs

@@ -1,4 +1,5 @@
 import { appendId, removeId, toggleId } from "./aria-ids.qwik.mjs";
+import { createContextProxy } from "./create-getter.qwik.mjs";
 import { createCache } from "./cache.qwik.mjs";
 import { hashString } from "./hash.qwik.mjs";
 import { hasIdInList } from "./id-list.qwik.mjs";
@@ -6,4 +7,4 @@ import { getIndexFromValue, getValueFromIndex, registerItem } from "./item-regis
 import { getNextEnabledIndex, getPrevEnabledIndex } from "./list-navigation.qwik.mjs";
 import { createSymbolName } from "./symbol.qwik.mjs";
 
-export { appendId, createCache, createSymbolName, getIndexFromValue, getNextEnabledIndex, getPrevEnabledIndex, getValueFromIndex, hasIdInList, hashString, registerItem, removeId, toggleId };
+export { appendId, createCache, createContextProxy, createSymbolName, getIndexFromValue, getNextEnabledIndex, getPrevEnabledIndex, getValueFromIndex, hasIdInList, hashString, registerItem, removeId, toggleId };

package/lib/index.qwik.mjs

@@ -1,4 +1,5 @@
 import { appendId, removeId, toggleId } from "./helpers/aria-ids.qwik.mjs";
+import { createContextProxy } from "./helpers/create-getter.qwik.mjs";
 import { createCache } from "./helpers/cache.qwik.mjs";
 import { hashString } from "./helpers/hash.qwik.mjs";
 import { hasIdInList } from "./helpers/id-list.qwik.mjs";
@@ -18,4 +19,4 @@ import { useStoreSignal } from "./state/store-signal.qwik.mjs";
 import "./state/index.qwik.mjs";
 import { addWindowEventListener, removeWindowEventListener } from "./types/window-events.qwik.mjs";
 
-export { addWindowEventListener, appendId, createCache, createSymbolName, destructureBindings, getIndexFromValue, getNextEnabledIndex, getPrevEnabledIndex, getValueFromIndex, hasIdInList, hashString, livePropsContextId, mergeRefs, registerItem, removeId, removeWindowEventListener, toggleId, useBindings, useBoundSignal, useDebouncer, useMountTask$, useMountTaskQrl, usePlayground, useResumed$, useResumedQrl, useStoreSignal };
+export { addWindowEventListener, appendId, createCache, createContextProxy, createSymbolName, destructureBindings, getIndexFromValue, getNextEnabledIndex, getPrevEnabledIndex, getValueFromIndex, hasIdInList, hashString, livePropsContextId, mergeRefs, registerItem, removeId, removeWindowEventListener, toggleId, useBindings, useBoundSignal, useDebouncer, useMountTask$, useMountTaskQrl, usePlayground, useResumed$, useResumedQrl, useStoreSignal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qds.dev/base",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "private": false,
   "description": "Create a Qwik library",
   "license": "MIT",