@alloy-js/core 0.23.0-dev.8 → 0.23.0

package/docs/api/functions/createMemberTap.md

@@ -0,0 +1,20 @@
+# createMemberTap
+
+Create a tap for [MemberDeclaration context](../../contexts/memberdeclaration-context/).
+
+```ts
+import { createMemberTap } from "@alloy-js/core";
+
+
+function createMemberTap<TSymbol extends OutputSymbol = OutputSymbol>(handler?: TapHandler<TSymbol>): Tap<TSymbol>;
+```
+
+## Parameters
+
+|         |                               |   |
+| ------- | ----------------------------- | - |
+| handler | optional TapHandler\<TSymbol> |   |
+
+## Returns
+
+[Tap](../../types/tap/)\<TSymbol>

package/docs/api/functions/createNamePolicy.md

@@ -0,0 +1,37 @@
+# createNamePolicy
+
+Creates a name policy that transforms symbol names based on element kind.
+
+```ts
+import { createNamePolicy } from "@alloy-js/core";
+
+
+function createNamePolicy<T extends string>(namer: (name: string, element: T) => string): NamePolicy<T>;
+```
+
+## Parameters
+
+|       |                                      |   |
+| ----- | ------------------------------------ | - |
+| namer | (name: string, element: T) => string |   |
+
+## Returns
+
+[NamePolicy](../../types/namepolicy/)\<T>
+
+## Remarks
+
+`element` identifies the kind of declaration (e.g., `"value"`, `"type"`). The set of valid element strings is defined by the language package.
+
+When `element` is `undefined` (outside a declaration context), \[unresolved link] and \[unresolved link] short-circuit and return the original name unchanged — the namer callback is **not** invoked. The namer therefore always receives a defined `T`. This means names outside a declaration context cannot be transformed by the policy.
+
+## Example
+
+```ts
+const policy = createNamePolicy((name, element) => {
+  if (element === "value") return toCamelCase(name);
+  if (element === "type")  return toPascalCase(name);
+  return name;
+});
+<Output namePolicy={policy}>...</Output>
+```

package/docs/api/functions/createNamedContext.md

@@ -0,0 +1,19 @@
+# createNamedContext
+
+```ts
+import { createNamedContext } from "@alloy-js/core";
+
+
+function createNamedContext<T>(name: string, defaultValue?: T): ComponentContext<T>;
+```
+
+## Parameters
+
+|              |            |   |
+| ------------ | ---------- | - |
+| name         | string     |   |
+| defaultValue | optional T |   |
+
+## Returns
+
+[ComponentContext](../../types/componentcontext/)\<T>

package/docs/api/functions/createOutputBinder.md

@@ -0,0 +1,24 @@
+# createOutputBinder
+
+```ts
+import { createOutputBinder } from "@alloy-js/core";
+
+
+function createOutputBinder(options?: BinderOptions): Binder;
+```
+
+## Parameters
+
+|         |                        |   |
+| ------- | ---------------------- | - |
+| options | optional BinderOptions |   |
+
+## Options
+
+|                      |                                                                    |   |
+| -------------------- | ------------------------------------------------------------------ | - |
+| nameConflictResolver | optional [NameConflictResolver](../../types/nameconflictresolver/) |   |
+
+## Returns
+
+[Binder](../../types/binder/)

package/docs/api/functions/createRenderTreeHook.md

@@ -0,0 +1,19 @@
+# createRenderTreeHook
+
+```ts
+import { createRenderTreeHook } from "@alloy-js/core";
+
+
+function createRenderTreeHook(subtree: RenderedTextTree, hooks: Omit<PrintHook, typeof printHookTag | "subtree">): PrintHook;
+```
+
+## Parameters
+
+|         |                                                    |   |
+| ------- | -------------------------------------------------- | - |
+| subtree | RenderedTextTree                                   |   |
+| hooks   | Omit\<PrintHook, typeof printHookTag \| “subtree”> |   |
+
+## Returns
+
+[PrintHook](../../types/printhook/)

package/docs/api/functions/createResource.md

@@ -0,0 +1,77 @@
+# createResource
+
+## Overload 1
+
+Create a resource that fetches data asynchronously.
+
+This function has two overloads:
+
+1. Simple fetcher - fetches data once when the resource is created
+2. Reactive fetcher - fetches data when a reactive source changes
+
+```ts
+import { createResource } from "@alloy-js/core";
+
+
+function createResource<U>(fetcher: () => Promise<U>): Resource<U>;
+```
+
+### Parameters
+
+|         |                   |   |
+| ------- | ----------------- | - |
+| fetcher | () => Promise\<U> |   |
+
+### Returns
+
+[Resource](../../types/resource/)\<U>
+
+### Examples
+
+```typescript
+// Simple usage - fetches data once when created
+const userResource = createResource(async () => {
+  const response = await fetch('/api/user');
+  return response.json();
+});
+
+// Access the resource state
+console.log(userResource.loading); // true initially
+console.log(userResource.data);    // null initially
+console.log(userResource.error);   // null initially
+```
+
+```typescript
+// Reactive usage - fetches data when the ref changes
+const userId = ref(1);
+
+const userResource = createResource(userId, async (id) => {
+  const response = await fetch(`/api/user/${id}`);
+  return response.json();
+});
+
+// The fetcher will be called automatically when userId changes
+userId.value = 2; // This triggers a new fetch with id=2
+```
+
+## Overload 2
+
+Create a resource that fetches data asynchronously based on a reactive source.
+
+```ts
+import { createResource } from "@alloy-js/core";
+
+
+function createResource<T, U>(refSource: Ref<T> | (() => T), fetcher: (input: T) => Promise<U>): Resource<U>;
+```
+
+### Parameters
+
+|           |                           |   |
+| --------- | ------------------------- | - |
+| refSource | Ref\<T> \| (() => T)      |   |
+| fetcher   | (input: T) => Promise\<U> |   |
+
+### Returns
+
+[Resource](../../types/resource/)\<U>

package/docs/api/functions/createScope.md

@@ -0,0 +1,35 @@
+# createScope
+
+Construct a scope instance and register it with devtools. Prefer this over calling `new` directly so that debugging tools can track the scope.
+
+```ts
+import { createScope } from "@alloy-js/core";
+
+
+function createScope<TScope extends OutputScope, Args extends unknown[]>(ctor: new (...args: Args) => TScope, ...args: Args): TScope;
+```
+
+## Parameters
+
+|      |                             |   |
+| ---- | --------------------------- | - |
+| ctor | new (…args: Args) => TScope |   |
+| args | Args                        |   |
+
+## Returns
+
+TScope
+
+## Remarks
+
+Inside a component, obtain the current scope with `useScope()` and pass it as the `parentScope` constructor argument so the new scope is wired into the scope tree.
+
+## Example
+
+```tsx
+function MyScope(props) {
+  const parentScope = useScope();
+  const scope = createScope(MyScope, "scope-name", parentScope);
+  return <Scope value={scope}>{props.children}</Scope>;
+}
+```

package/docs/api/functions/createScopeTap.md

@@ -0,0 +1,20 @@
+# createScopeTap
+
+Create a tap for [OutputScope](../../types/outputscope/).
+
+```ts
+import { createScopeTap } from "@alloy-js/core";
+
+
+function createScopeTap<TScope extends OutputScope = OutputScope>(handler?: TapHandler<TScope>): Tap<TScope>;
+```
+
+## Parameters
+
+|         |                              |   |
+| ------- | ---------------------------- | - |
+| handler | optional TapHandler\<TScope> |   |
+
+## Returns
+
+[Tap](../../types/tap/)\<TScope>

package/docs/api/functions/createSourceFileTap.md

@@ -0,0 +1,20 @@
+# createSourceFileTap
+
+Create a tap for [SourceFile context interface](../../contexts/sourcefile-context/).
+
+```ts
+import { createSourceFileTap } from "@alloy-js/core";
+
+
+function createSourceFileTap(handler?: TapHandler<SourceFileContext>): Tap<SourceFileContext>;
+```
+
+## Parameters
+
+|         |                                         |   |
+| ------- | --------------------------------------- | - |
+| handler | optional TapHandler\<SourceFileContext> |   |
+
+## Returns
+
+[Tap](../../types/tap/)<[SourceFile context interface](../../contexts/sourcefile-context/)>

package/docs/api/functions/createSymbol.md

@@ -0,0 +1,25 @@
+# createSymbol
+
+Construct a symbol instance and register it with devtools. Prefer this over calling `new` directly so that debugging tools can track the symbol.
+
+```ts
+import { createSymbol } from "@alloy-js/core";
+
+
+function createSymbol<TSymbol extends OutputSymbol, Args extends unknown[]>(ctor: new (...args: Args) => TSymbol, ...args: Args): TSymbol;
+```
+
+## Parameters
+
+|      |                              |   |
+| ---- | ---------------------------- | - |
+| ctor | new (…args: Args) => TSymbol |   |
+| args | Args                         |   |
+
+## Returns
+
+TSymbol
+
+## Remarks
+
+Binder registration (via `useBinder()` + `notifySymbolCreated()`) happens inside the [`OutputSymbol`](../types/OutputSymbol.md) constructor regardless of whether you use `createSymbol` or `new`. This helper only adds devtools registration.

package/docs/api/functions/createSymbolSlot.md

@@ -0,0 +1,19 @@
+# createSymbolSlot
+
+Create a component which accepts emitted symbols. The returned component has a `ref` property which is a ref to a reactive set of all symbols emitted by children of the component.
+
+```ts
+import { createSymbolSlot } from "@alloy-js/core";
+
+
+function createSymbolSlot(): SymbolSlot;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+[SymbolSlot](../../types/symbolslot/)

package/docs/api/functions/createTap.md

@@ -0,0 +1,55 @@
+# createTap
+
+Create a component that when rendered, initializes the tapped value with the provided callback. This is useful for accessing context provided by child components inside a parent component.
+
+```ts
+import { createTap } from "@alloy-js/core";
+
+
+function createTap<T = unknown>(tapper: Tapper<T>, handler?: TapHandler<T>): Tap<T>;
+```
+
+## Parameters
+
+|         |                         |   |
+| ------- | ----------------------- | - |
+| tapper  | Tapper\<T>              |   |
+| handler | optional TapHandler\<T> |   |
+
+## Returns
+
+[Tap](../../types/tap/)\<T>
+
+## Example
+
+```tsx
+import { type Children, computed, createTap } from "@alloy-js/core";
+
+// context we will tap into
+const SomeContext = createContext<string>();
+
+// a component which provides some specific context
+function MyDeclaration(props: { children: Children }) {
+  return <SomeContext.Provider value="Hello World">
+    {props.children}
+  </SomeContext.Provider>;
+}
+
+// a parent component which wants to know about the context set
+// by its children
+function MySpecialDeclaration() {
+  const SomeContextTap = createTap(() => useContext(SomeContext));
+
+  return <>
+    The declaration context is: {SomeContextTap.ref}
+    <MyDeclaration>
+      <SomeContextTap />
+    </MyDeclaration>
+  </>
+}
+
+@see {@link createDeclarationTap} for tapping {@link DeclarationContext}.
+@see {@link createMemberTap} for tapping {@link MemberDeclarationContext}.
+@see {@link createScopeTap} for tapping {@link OutputScope}.
+@see {@link createSourceFileTap} for tapping {@link SourceFileContext}.
+```

package/docs/api/functions/decl.md

@@ -0,0 +1,20 @@
+# decl
+
+Create a declaration in the current scope with the given namekey. Only works with basic scopes. Import `decl` from a specific language library for declaring language-specific symbols.
+
+```ts
+import { decl } from "@alloy-js/core";
+
+
+function decl(namekey: Namekey): import("../runtime/component.js").ComponentCreator<{}>;
+```
+
+## Parameters
+
+|         |         |   |
+| ------- | ------- | - |
+| namekey | Namekey |   |
+
+## Returns
+
+import(”../runtime/component.js”).[ComponentCreator](../../types/componentcreator/)<{}>

package/docs/api/functions/defaultProps.md

@@ -0,0 +1,21 @@
+# defaultProps
+
+Applies default values to a props object. Reactive props are handled properly by ensuring that their value is not accessed by `defaultProps`, avoiding any unintended side effects.
+
+```ts
+import { defaultProps } from "@alloy-js/core";
+
+
+function defaultProps<T extends {}>(props: T, defaults: Partial<T>): T;
+```
+
+## Parameters
+
+|          |             |   |
+| -------- | ----------- | - |
+| props    | T           |   |
+| defaults | Partial\<T> |   |
+
+## Returns
+
+T

package/docs/api/functions/effect.md

@@ -0,0 +1,26 @@
+# effect
+
+```ts
+import { effect } from "@alloy-js/core";
+
+
+function effect<T>(fn: (prev?: T) => T, current?: T, options?: EffectOptions): void;
+```
+
+## Parameters
+
+|         |                        |   |
+| ------- | ---------------------- | - |
+| fn      | (prev?: T) => T        |   |
+| current | optional T             |   |
+| options | optional EffectOptions |   |
+
+## Options
+
+|       |                                                                |   |
+| ----- | -------------------------------------------------------------- | - |
+| debug | optional [EffectDebugOptions](../../types/effectdebugoptions/) |   |
+
+## Returns
+
+void

package/docs/api/functions/emitDiagnostic.md

@@ -0,0 +1,18 @@
+# emitDiagnostic
+
+```ts
+import { emitDiagnostic } from "@alloy-js/core";
+
+
+function emitDiagnostic(input: DiagnosticInput): DiagnosticHandle;
+```
+
+## Parameters
+
+|       |                 |   |
+| ----- | --------------- | - |
+| input | DiagnosticInput |   |
+
+## Returns
+
+[DiagnosticHandle](../../types/diagnostichandle/)

package/docs/api/functions/emitSymbol.md

@@ -0,0 +1,18 @@
+# emitSymbol
+
+```ts
+import { emitSymbol } from "@alloy-js/core";
+
+
+function emitSymbol(symbol: OutputSymbol | Ref<OutputSymbol | undefined>): void;
+```
+
+## Parameters
+
+|        |                                                 |   |
+| ------ | ----------------------------------------------- | - |
+| symbol | OutputSymbol \| Ref\<OutputSymbol \| undefined> |   |
+
+## Returns
+
+void

package/docs/api/functions/ensureIsEmpty.md

@@ -0,0 +1,20 @@
+# ensureIsEmpty
+
+Ensure that a context has an isEmpty ref, creating one if needed. Only call this when you need to reactively observe isEmpty (e.g., ContentSlot, mapJoin). Most contexts don’t need an isEmpty ref.
+
+```ts
+import { ensureIsEmpty } from "@alloy-js/core";
+
+
+function ensureIsEmpty(context: Context): Ref<boolean>;
+```
+
+## Parameters
+
+|         |         |   |
+| ------- | ------- | - |
+| context | Context |   |
+
+## Returns
+
+Ref\<boolean>

package/docs/api/functions/findCurrentEffectId.md

@@ -0,0 +1,19 @@
+# findCurrentEffectId
+
+Walk up the context owner chain to find the nearest effect ID. Used to attribute reactive mutations to the effect that caused them.
+
+```ts
+import { findCurrentEffectId } from "@alloy-js/core";
+
+
+function findCurrentEffectId(): number | undefined;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+number | undefined

package/docs/api/functions/findKeyedChild.md

@@ -0,0 +1,19 @@
+# findKeyedChild
+
+```ts
+import { findKeyedChild } from "@alloy-js/core";
+
+
+function findKeyedChild(children: Children[], tag: symbol): ComponentCreator<import("./runtime/component.js").Props> | null;
+```
+
+## Parameters
+
+|          |             |   |
+| -------- | ----------- | - |
+| children | Children\[] |   |
+| tag      | symbol      |   |
+
+## Returns
+
+[ComponentCreator](../../types/componentcreator/)\<import(”./runtime/component.js”).[Props](../../types/props/)> | null

package/docs/api/functions/findKeyedChildren.md

@@ -0,0 +1,19 @@
+# findKeyedChildren
+
+```ts
+import { findKeyedChildren } from "@alloy-js/core";
+
+
+function findKeyedChildren(children: Children[], tag: symbol): ComponentCreator<import("./runtime/component.js").Props>[];
+```
+
+## Parameters
+
+|          |             |   |
+| -------- | ----------- | - |
+| children | Children\[] |   |
+| tag      | symbol      |   |
+
+## Returns
+
+[ComponentCreator](../../types/componentcreator/)\<import(”./runtime/component.js”).[Props](../../types/props/)>\[]

package/docs/api/functions/findUnkeyedChildren.md

@@ -0,0 +1,18 @@
+# findUnkeyedChildren
+
+```ts
+import { findUnkeyedChildren } from "@alloy-js/core";
+
+
+function findUnkeyedChildren(children: Children[]): Children[];
+```
+
+## Parameters
+
+|          |             |   |
+| -------- | ----------- | - |
+| children | Children\[] |   |
+
+## Returns
+
+[Children](../../types/children/)\[]

package/docs/api/functions/formatReactivePropertyLabel.md

@@ -0,0 +1,21 @@
+# formatReactivePropertyLabel
+
+Build a human-readable label for a reactive property like `symbolName.prop`.
+
+```ts
+import { formatReactivePropertyLabel } from "@alloy-js/core";
+
+
+function formatReactivePropertyLabel(target: object, key: string | number): string;
+```
+
+## Parameters
+
+|        |                  |   |
+| ------ | ---------------- | - |
+| target | object           |   |
+| key    | string \| number |   |
+
+## Returns
+
+string

package/docs/api/functions/getAssignmentSymbol.md

@@ -0,0 +1,19 @@
+# getAssignmentSymbol
+
+Get the symbol being defined.
+
+```ts
+import { getAssignmentSymbol } from "@alloy-js/core";
+
+
+function getAssignmentSymbol(): OutputSymbol | undefined;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+[OutputSymbol](../../types/outputsymbol/) | undefined The symbol currently being defined, or `undefined` if no symbol is being defined.

package/docs/api/functions/getContext.md

@@ -0,0 +1,17 @@
+# getContext
+
+```ts
+import { getContext } from "@alloy-js/core";
+
+
+function getContext(): Context | null;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+[Context](../../types/context/) | null

package/docs/api/functions/getContextForRenderNode.md

@@ -0,0 +1,18 @@
+# getContextForRenderNode
+
+```ts
+import { getContextForRenderNode } from "@alloy-js/core";
+
+
+function getContextForRenderNode(node: RenderedTextTree): Context | undefined;
+```
+
+## Parameters
+
+|      |                  |   |
+| ---- | ---------------- | - |
+| node | RenderedTextTree |   |
+
+## Returns
+
+[Context](../../types/context/) | undefined