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

package/docs/api/components/createAccessExpression.md

@@ -0,0 +1,55 @@
+# createAccessExpression
+
+Create a language-specific access/member expression component pair.
+
+Returns `{ Expression, Part }` where:
+
+* `Expression` is the main component that collects Part children and renders the chain
+* `Part` is a no-op component whose props are consumed by Expression
+
+The factory handles:
+
+* Children collection and Part filtering
+* Symbol resolution (refkey → symbol via binder, single computed per part)
+* Reactive optimization (getter delegation over single computed per part)
+* Flattening nested Expression instances
+* `takeSymbols()` to prevent symbol leakage
+* Call chain detection and chunked formatting algorithm
+
+Configuration for creating a language-specific access expression component.
+
+* jsx
+
+  ```tsx
+  import { createAccessExpression } from "@alloy-js/core";
+
+
+  <createAccessExpression  />
+  ```
+
+* stc
+
+  ```ts
+  import { createAccessExpression } from "@alloy-js/core/stc";
+
+
+  createAccessExpression({
+    canUseCallChains: undefined,
+    createDescriptor: undefined,
+    formatPart: undefined,
+    getBase: undefined,
+    isCallPart: undefined,
+    wrapPartResult: undefined,
+  }).children(children)
+  ```
+
+## Props
+
+|                  |                                                                                 |                                                                                                                                                                                                                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| canUseCallChains | (parts: TPart\[]) => boolean                                                    | Additional check for whether call chain formatting should be used. Called only when `isCallPart` is provided and more than one call is detected. Return false to force linear formatting (e.g., TypeScript disables call chains when any part has `await`). Defaults to `() => true`. |
+| createDescriptor | (props: TPartProps, symbol: OutputSymbol \| undefined, first: boolean) => TPart | Convert Part props + resolved symbol into a plain descriptor object. Called once per Part during children processing. The returned descriptor is wrapped in a computed + getter delegation for reactive optimization.                                                                 |
+| formatPart       | (part: TPart, prevPart: TPart, inCallChain: boolean) => Children                | Format a non-first part given its descriptor and the previous part. Returns JSX children for that segment (e.g., `.foo`, `?.bar`, `[idx]`, `(args)`). `inCallChain` is true when rendering inside a chunked call chain.                                                               |
+| getBase          | (part: TPart) => Children                                                       | Extract the base content from the first part (the leftmost identifier).                                                                                                                                                                                                               |
+| isCallPart       | (part: TPart) => boolean                                                        | Identify which parts are function calls, for call chain detection. When provided, the factory uses the chunked call chain algorithm (line breaks after each call group) when more than one call is detected. When omitted, the expression is always formatted linearly.               |
+| wrapPartResult   | (expression: Children, part: TPart, index: number, isLast: boolean) => Children | Post-process the accumulated expression after each part in linear (non-call-chain) mode. Use this for language-specific wrapping like TypeScript’s `await` which wraps the entire expression so far. Defaults to identity (returns expression unchanged).                             |

package/docs/api/components/index.md

@@ -0,0 +1,27 @@
+# core — components
+
+- [AppendRegion](AppendRegion.md) — import { AppendRegion } from "@alloy-js/core";
+- [Block](Block.md) — Create an indented block of source text.
+- [CopyFile](CopyFile.md) — import { CopyFile } from "@alloy-js/core";
+- [createAccessExpression](createAccessExpression.md) — Create a language-specific access/member expression component pair.
+- [Declaration](Declaration.md) — Declares a symbol in the current scope for this component’s children.
+- [For](For.md) — The For component iterates over the provided array and invokes the child callback for each item.
+- [Indent](Indent.md) — Create an indented block of source text.
+- [List](List.md) — Create a list of children with text between each child.
+- [MemberDeclaration](MemberDeclaration.md) — Declares a symbol in the current member scope for this component’s children.
+- [MemberName](MemberName.md) — Renders the name of the current member declaration from [MemberDeclaration context](../../contexts/memberdeclaration-context/).
+- [MemberScope](MemberScope.md) — Declare a member scope, which is a lexical scope whose symbols are provided by the owner symbol.
+- [Name](Name.md) — import { Name } from "@alloy-js/core";
+- [Output](Output.md) — This component is the root component for all your emitted output.
+- [Prose](Prose.md) — Create a block of text which will break once a word exceeds the configured line width.
+- [ReferenceOrContent](ReferenceOrContent.md) — import { ReferenceOrContent } from "@alloy-js/core";
+- [Scope](Scope.md) — Declare a scope for this component’s children.
+- [Show](Show.md) — import { Show } from "@alloy-js/core";
+- [SourceDirectory](SourceDirectory.md) — import { SourceDirectory } from "@alloy-js/core";
+- [SourceFile](SourceFile.md) — import { SourceFile } from "@alloy-js/core";
+- [StatementList](StatementList.md) — Join child elements with semicolons and hardlines.
+- [Switch](Switch.md) — Conditionally render blocks of content based on the `when` prop of nested [Match](../../variables/match/) components.
+- [TemplateFile](TemplateFile.md) — A component that reads a template file and replaces variable placeholders with actual values.
+- [TemplateVariable](TemplateVariable.md) — import { TemplateVariable } from "@alloy-js/core";
+- [UpdateFile](UpdateFile.md) — A component for updating existing files or initializing new files.
+- [Wrap](Wrap.md) — Conditionally wrap the children of this component with the component given to `with` and passing `props` to it.

package/docs/api/contexts/Assignment-context.md

@@ -0,0 +1,43 @@
+# Assignment context
+
+AssignmentContext provides the symbol that is the target of the current assignment.
+
+```ts
+const AssignmentContext: ComponentContext<AssignmentContext>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(AssignmentContext);
+```
+
+## Context interface
+
+|            |                                           |                                                                                                                                   |
+| ---------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| isAssigned | boolean                                   | Whether the symbol has had a value assigned to it. Once the symbol has been assigned, subsequent assignments will have no effect. |
+| target     | [OutputSymbol](../../types/outputsymbol/) | The symbol that is the target of the current assignment.                                                                          |
+
+## Factory
+
+```ts
+import { createAssignmentContext } from "@alloy-js/core";
+
+
+function createAssignmentContext(target: OutputSymbol): AssignmentContext;
+```
+
+Creates a new [Assignment context interface](../assignment-context/).
+
+### Parameters
+
+|        |              |   |
+| ------ | ------------ | - |
+| target | OutputSymbol |   |
+
+## Remarks
+
+When a variable is declared, the symbol for the variable doesn’t yet know what value it will hold, because that depends on the assignment to the variable in the variable declaration’s initializer. This context provides the symbol that is the target of the current assignment, so that children of an assignment or initializer can provide additional symbol information.
+
+For example, when assigning an object value expression to a variable, the object value expression should use assignment context to provide the member symbols for the object value’s properties.

package/docs/api/contexts/Binder-context.md

@@ -0,0 +1,22 @@
+# Binder context
+
+The binder context provides the binder instance to all components. This context is provided by the [output component](../../components/output/).
+
+```ts
+const BinderContext: ComponentContext<Binder>
+```
+
+## Accessor
+
+```ts
+import { useBinder } from "@alloy-js/core";
+
+
+const myContext = useBinder();
+```
+
+Returns the current [Binder](../../types/binder/) from context, or `undefined` if no binder is available. The binder is provided by the [Output](../../components/output/) component.
+
+## Context interface
+
+[Binder](../../types/binder/)

package/docs/api/contexts/Declaration-context.md

@@ -0,0 +1,15 @@
+# Declaration context
+
+```ts
+const DeclarationContext: ComponentContext<OutputSymbol>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(DeclarationContext);
+```
+
+## Context interface
+
+[OutputSymbol](../../types/outputsymbol/)

package/docs/api/contexts/Member-context.md

@@ -0,0 +1,17 @@
+# Member context
+
+```ts
+const MemberContext: ComponentContext<MemberContext>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(MemberContext);
+```
+
+## Context interface
+
+|             |                                           |   |
+| ----------- | ----------------------------------------- | - |
+| ownerSymbol | [OutputSymbol](../../types/outputsymbol/) |   |

package/docs/api/contexts/MemberDeclaration-context.md

@@ -0,0 +1,24 @@
+# MemberDeclaration context
+
+Provides the symbol for the member currently being declared.
+
+```ts
+const MemberDeclarationContext: ComponentContext<OutputSymbol>
+```
+
+## Accessor
+
+```ts
+import { useMemberDeclaration } from "@alloy-js/core";
+
+
+const myContext = useMemberDeclaration();
+```
+
+## Context interface
+
+[OutputSymbol](../../types/outputsymbol/)
+
+## See also
+
+* [Declaration context](../declaration-context/) for getting the symbol for the current non-member declaration.

package/docs/api/contexts/NamePolicy-context.md

@@ -0,0 +1,18 @@
+# NamePolicy context
+
+```ts
+const NamePolicyContext: ComponentContext<NamePolicy<string>>
+```
+
+## Accessor
+
+```ts
+import { useNamePolicy } from "@alloy-js/core";
+
+
+const myContext = useNamePolicy();
+```
+
+## Context interface
+
+[NamePolicy](../../types/namepolicy/)

package/docs/api/contexts/Scope-context.md

@@ -0,0 +1,20 @@
+# Scope context
+
+```ts
+const ScopeContext: ComponentContext<OutputScope>
+```
+
+## Accessor
+
+```ts
+import { useScope } from "@alloy-js/core";
+
+
+const myContext = useScope();
+```
+
+Returns the current [OutputScope](../../types/outputscope/) from context. Must be called inside a component that is a descendant of a `<Scope>` provider.
+
+## Context interface
+
+[OutputScope](../../types/outputscope/)

package/docs/api/contexts/SourceDirectory-context.md

@@ -0,0 +1,26 @@
+# SourceDirectory context
+
+Always provided by `<Output>` — `useContext(SourceDirectoryContext)` is never `undefined` inside an `<Output>` tree. At the root of the tree, `path` equals the `basePath` prop on `<Output>` (default `"./"`); nested `<SourceDirectory>` components update `path` relative to their parent.
+
+```ts
+const SourceDirectoryContext: ComponentContext<SourceDirectoryContext>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(SourceDirectoryContext);
+```
+
+## Context interface
+
+|            |                                                                                                                                                                                    |   |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
+| addContent | (content: SourceDirectoryContext \| SourceFileContext \| CopyFileContext) => void                                                                                                  |   |
+| contents   | ([SourceDirectory context interface](../sourcedirectory-context/) \| [SourceFile context interface](../sourcefile-context/) \| [CopyFileContext](../../types/copyfilecontext/))\[] |   |
+| path       | string                                                                                                                                                                             |   |
+
+## See also
+
+* [Output](../../components/output/)
+* [SourceDirectory](../../components/sourcedirectory/)

package/docs/api/contexts/SourceFile-context.md

@@ -0,0 +1,19 @@
+# SourceFile context
+
+```ts
+const SourceFileContext: ComponentContext<SourceFileContext>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(SourceFileContext);
+```
+
+## Context interface
+
+|           |                                                                                                              |   |
+| --------- | ------------------------------------------------------------------------------------------------------------ | - |
+| filetype  | string                                                                                                       |   |
+| path      | string                                                                                                       |   |
+| reference | optional [ComponentDefinition](../../types/componentdefinition/)<{ refkey: [Refkey](../../types/refkey/); }> |   |

package/docs/api/contexts/index.md

@@ -0,0 +1,11 @@
+# core — contexts
+
+- [Assignment context](Assignment-context.md) — AssignmentContext provides the symbol that is the target of the current assignment.
+- [Binder context](Binder-context.md) — The binder context provides the binder instance to all components.
+- [Declaration context](Declaration-context.md) — const DeclarationContext: ComponentContext<OutputSymbol>
+- [Member context](Member-context.md) — const MemberContext: ComponentContext<MemberContext>
+- [MemberDeclaration context](MemberDeclaration-context.md) — Provides the symbol for the member currently being declared.
+- [NamePolicy context](NamePolicy-context.md) — const NamePolicyContext: ComponentContext<NamePolicy<string>>
+- [Scope context](Scope-context.md) — const ScopeContext: ComponentContext<OutputScope>
+- [SourceDirectory context](SourceDirectory-context.md) — Always provided by `<Output>` — `useContext(SourceDirectoryContext)` is never `undefined` inside an `<Output>` tree.
+- [SourceFile context](SourceFile-context.md) — const SourceFileContext: ComponentContext<SourceFileContext>

package/docs/api/functions/attachDiagnosticsCollector.md

@@ -0,0 +1,18 @@
+# attachDiagnosticsCollector
+
+```ts
+import { attachDiagnosticsCollector } from "@alloy-js/core";
+
+
+function attachDiagnosticsCollector(collector: DiagnosticsCollector): void;
+```
+
+## Parameters
+
+|           |                      |   |
+| --------- | -------------------- | - |
+| collector | DiagnosticsCollector |   |
+
+## Returns
+
+void

package/docs/api/functions/baseListPropsToMapJoinArgs.md

@@ -0,0 +1,20 @@
+# baseListPropsToMapJoinArgs
+
+Convert a list of props to a joiner and ender for use in [mapJoin](../mapjoin/).
+
+```ts
+import { baseListPropsToMapJoinArgs } from "@alloy-js/core";
+
+
+function baseListPropsToMapJoinArgs(props: BaseListProps): JoinOptions;
+```
+
+## Parameters
+
+|       |               |   |
+| ----- | ------------- | - |
+| props | BaseListProps |   |
+
+## Returns
+
+[JoinOptions](../../types/joinoptions/)

package/docs/api/functions/children.md

@@ -0,0 +1,27 @@
+# children
+
+Returns a memo which is a list of all the provided children. If you want this as an array, see [childrenArray](../childrenarray/).
+
+```ts
+import { children } from "@alloy-js/core";
+
+
+function children(fn: () => Children, options?: ChildrenOptions): () => Children;
+```
+
+## Parameters
+
+|         |                          |   |
+| ------- | ------------------------ | - |
+| fn      | () => Children           |   |
+| options | optional ChildrenOptions |   |
+
+## Options
+
+|                   |                  |                                                    |
+| ----------------- | ---------------- | -------------------------------------------------- |
+| preserveFragments | optional boolean | When true, fragments and arrays are not flattened. |
+
+## Returns
+
+() => [Children](../../types/children/)

package/docs/api/functions/childrenArray.md

@@ -0,0 +1,25 @@
+# childrenArray
+
+```ts
+import { childrenArray } from "@alloy-js/core";
+
+
+function childrenArray(fn: () => Children, options?: ChildrenOptions): Children[];
+```
+
+## Parameters
+
+|         |                          |   |
+| ------- | ------------------------ | - |
+| fn      | () => Children           |   |
+| options | optional ChildrenOptions |   |
+
+## Options
+
+|                   |                  |                                                    |
+| ----------------- | ---------------- | -------------------------------------------------- |
+| preserveFragments | optional boolean | When true, fragments and arrays are not flattened. |
+
+## Returns
+
+[Children](../../types/children/)\[]

package/docs/api/functions/code.md

@@ -0,0 +1,25 @@
+# code
+
+Turn the provided string template into Children by replacing literal line breaks with hardlines and automatically indenting indented content. Similar in spirit to the `<code>` element in HTML.
+
+```ts
+import { code } from "@alloy-js/core";
+
+
+function code(template: TemplateStringsArray, ...substitutions: Children[]): Children;
+```
+
+## Parameters
+
+|               |                      |   |
+| ------------- | -------------------- | - |
+| template      | TemplateStringsArray |   |
+| substitutions | Children\[]          |   |
+
+## Returns
+
+[Children](../../types/children/)
+
+## See also
+
+* [text](../text/) for a similar function which treats whitespace similar to JSX template bodies.

package/docs/api/functions/computed.md

@@ -0,0 +1,18 @@
+# computed
+
+```ts
+import { computed } from "@alloy-js/core";
+
+
+function computed<T>(getter: () => T): Ref<T>;
+```
+
+## Parameters
+
+|        |         |   |
+| ------ | ------- | - |
+| getter | () => T |   |
+
+## Returns
+
+Ref\<T>

package/docs/api/functions/createComponent.md

@@ -0,0 +1,20 @@
+# createComponent
+
+```ts
+import { createComponent } from "@alloy-js/core";
+
+
+function createComponent<TProps extends Props = Props>(C: Component<TProps>, props: TProps, source?: SourceLocation): ComponentCreator<TProps>;
+```
+
+## Parameters
+
+|        |                         |   |
+| ------ | ----------------------- | - |
+| C      | Component\<TProps>      |   |
+| props  | TProps                  |   |
+| source | optional SourceLocation |   |
+
+## Returns
+
+[ComponentCreator](../../types/componentcreator/)\<TProps>

package/docs/api/functions/createContentSlot.md

@@ -0,0 +1,33 @@
+# createContentSlot
+
+Create a component which tracks whether any content is placed inside of it. The component exposes a ref `isEmpty` which indicates whether the slot is empty, as well as convenience accessors `isEmpty` and `hasContent`. Additionally, it provides two sub-components, `WhenEmpty` and `WhenHasContent`, which render their contents conditionally based on whether the slot is empty.
+
+```ts
+import { createContentSlot } from "@alloy-js/core";
+
+
+function createContentSlot(): ContentSlot;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+[ContentSlot](../../types/contentslot/)
+
+## Example
+
+```tsx
+const ContentSlot = createContentSlot();
+
+<>
+  <ContentSlot.WhenEmpty>The slot is empty!</ContentSlot.WhenEmpty>
+  <ContentSlot.WhenHasContent>The slot has content!</ContentSlot.WhenHasContent>
+  <ContentSlot>
+    {someCondition && "Here is some content!"}
+  </ContentSlot>
+</>
+```

package/docs/api/functions/createContext.md

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

package/docs/api/functions/createCustomContext.md

@@ -0,0 +1,18 @@
+# createCustomContext
+
+```ts
+import { createCustomContext } from "@alloy-js/core";
+
+
+function createCustomContext(useCallback: (useChildren: CustomContextChildrenCallback) => void): CustomContext;
+```
+
+## Parameters
+
+|             |                                                      |   |
+| ----------- | ---------------------------------------------------- | - |
+| useCallback | (useChildren: CustomContextChildrenCallback) => void |   |
+
+## Returns
+
+[CustomContext](../../types/customcontext/)

package/docs/api/functions/createDeclarationTap.md

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

package/docs/api/functions/createFileResource.md

@@ -0,0 +1,35 @@
+# createFileResource
+
+Create a resource that reads a file from the file system.
+
+This is a convenience function that creates a resource for reading file content using the AlloyHost file system API. The file is read as text when the resource is created.
+
+```ts
+import { createFileResource } from "@alloy-js/core";
+
+
+function createFileResource(path: string): Resource<string>;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| path | string |   |
+
+## Returns
+
+[Resource](../../types/resource/)\<string>
+
+## Example
+
+```typescript
+// Read a configuration file
+const configResource = createFileResource('./config.json');
+
+// Access the file content
+if (!configResource.loading && !configResource.error) {
+  const configText = configResource.data; // string content of the file
+  const config = JSON.parse(configText);
+}
+```

package/docs/api/functions/createFormatOptionsContextFor.md

@@ -0,0 +1,28 @@
+# createFormatOptionsContextFor
+
+Create a format options context for a specific file type. Returns a `Provider` component and a `useFormatOptions` hook.
+
+```ts
+import { createFormatOptionsContextFor } from "@alloy-js/core";
+
+
+function createFormatOptionsContextFor<T>(filetype: string, defaults?: T): {
+    Provider: import("../index.js").ComponentDefinition<import("../context.js").ContextProviderProps<T>>;
+    useFormatOptions: (overrides?: Partial<T>) => T;
+};
+```
+
+## Parameters
+
+|          |            |   |
+| -------- | ---------- | - |
+| filetype | string     |   |
+| defaults | optional T |   |
+
+## Returns
+
+{ Provider: import(”../index.js”).[ComponentDefinition](../../types/componentdefinition/)\<import(”../context.js”).[ContextProviderProps](../../types/contextproviderprops/)\<T>>; useFormatOptions: (overrides?: Partial\<T>) => T; }
+
+## Remarks
+
+Merge precedence: `defaults` (lowest) → Provider `value` → `overrides` argument to `useFormatOptions()` (highest). Undefined override values are ignored.

package/docs/api/functions/createIntrinsic.md

@@ -0,0 +1,19 @@
+# createIntrinsic
+
+```ts
+import { createIntrinsic } from "@alloy-js/core";
+
+
+function createIntrinsic<TKey extends keyof IntrinsicElements>(name: TKey, props: IntrinsicElements[TKey]): IntrinsicElementBase<TKey>;
+```
+
+## Parameters
+
+|       |                          |   |
+| ----- | ------------------------ | - |
+| name  | TKey                     |   |
+| props | IntrinsicElements\[TKey] |   |
+
+## Returns
+
+[IntrinsicElementBase](../../types/intrinsicelementbase/)\<TKey>