@alloy-js/core 0.23.0-dev.9 → 0.24.0-dev.1

package/docs/api/functions/symbolForRefkey.md

@@ -0,0 +1,24 @@
+# symbolForRefkey
+
+Get a ref to the symbol for the given refkey using the current binder. The value of the ref will be undefined when no symbol with that refkey has been created.
+
+```ts
+import { symbolForRefkey } from "@alloy-js/core";
+
+
+function symbolForRefkey(refkey: Refkeyable): Ref<OutputSymbol | undefined, OutputSymbol | undefined>;
+```
+
+## Parameters
+
+|        |            |   |
+| ------ | ---------- | - |
+| refkey | Refkeyable |   |
+
+## Returns
+
+Ref<[OutputSymbol](../../types/outputsymbol/) | undefined, [OutputSymbol](../../types/outputsymbol/) | undefined>
+
+## Remarks
+
+This API may return a ref for undefined, but that does not mean that the symbol is not found. The symbol you’re looking for may not have been declared yet. When the symbol is declared, the ref will be updated with the symbol.

package/docs/api/functions/taggedComponent.md

@@ -0,0 +1,19 @@
+# taggedComponent
+
+```ts
+import { taggedComponent } from "@alloy-js/core";
+
+
+function taggedComponent<TProps = Props>(tag: symbol, component: Component<TProps>): Component<TProps> & Required<Pick<Component<TProps>, "tag">>;
+```
+
+## Parameters
+
+|           |                    |   |
+| --------- | ------------------ | - |
+| tag       | symbol             |   |
+| component | Component\<TProps> |   |
+
+## Returns
+
+[Component](../../../typescript/components/ensuretyperefcontext/)\<TProps> & Required\<Pick<[Component](../../../typescript/components/ensuretyperefcontext/)\<TProps>, “tag”>>

package/docs/api/functions/takeSymbols.md

@@ -0,0 +1,18 @@
+# takeSymbols
+
+```ts
+import { takeSymbols } from "@alloy-js/core";
+
+
+function takeSymbols(cb?: (symbol: OutputSymbol) => void): import("@vue/reactivity").ShallowReactive<Set<OutputSymbol>>;
+```
+
+## Parameters
+
+|    |                                         |   |
+| -- | --------------------------------------- | - |
+| cb | optional (symbol: OutputSymbol) => void |   |
+
+## Returns
+
+import(“@vue/reactivity”).ShallowReactive\<Set<[OutputSymbol](../../types/outputsymbol/)>>

package/docs/api/functions/text.md

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

package/docs/api/functions/toRef.md

@@ -0,0 +1,20 @@
+# toRef
+
+```ts
+import { toRef } from "@alloy-js/core";
+
+
+function toRef<T extends object, K extends keyof T>(object: T, key: K, defaultValue?: T[K]): Ref<T[K]>;
+```
+
+## Parameters
+
+|              |                |   |
+| ------------ | -------------- | - |
+| object       | T              |   |
+| key          | K              |   |
+| defaultValue | optional T\[K] |   |
+
+## Returns
+
+Ref\<T\[K]>

package/docs/api/functions/toRefkey.md

@@ -0,0 +1,18 @@
+# toRefkey
+
+```ts
+import { toRefkey } from "@alloy-js/core";
+
+
+function toRefkey(refkey: Refkeyable): Refkey;
+```
+
+## Parameters
+
+|        |            |   |
+| ------ | ---------- | - |
+| refkey | Refkeyable |   |
+
+## Returns
+
+[Refkey](../../types/refkey/)

package/docs/api/functions/toRefs.md

@@ -0,0 +1,20 @@
+# toRefs
+
+```ts
+import { toRefs } from "@alloy-js/core";
+
+
+function toRefs<T extends object>(object: T): {
+    [K in keyof T]: Ref<T[K]>;
+};
+```
+
+## Parameters
+
+|        |   |   |
+| ------ | - | - |
+| object | T |   |
+
+## Returns
+
+{ \[K in keyof T]: Ref\<T\[K]>; }

package/docs/api/functions/traverseOutput.md

@@ -0,0 +1,21 @@
+# traverseOutput
+
+Traverse the output from [render](../render/) and call the visitor for each file and directory within it.
+
+```ts
+import { traverseOutput } from "@alloy-js/core";
+
+
+function traverseOutput(sourceDirectory: OutputDirectory, visitor: OutputVisitor): Promise<void>;
+```
+
+## Parameters
+
+|                 |                 |   |
+| --------------- | --------------- | - |
+| sourceDirectory | OutputDirectory |   |
+| visitor         | OutputVisitor   |   |
+
+## Returns
+
+Promise\<void>

package/docs/api/functions/unresolvedRefkey.md

@@ -0,0 +1,18 @@
+# unresolvedRefkey
+
+```ts
+import { unresolvedRefkey } from "@alloy-js/core";
+
+
+function unresolvedRefkey(refkey: Refkey): string;
+```
+
+## Parameters
+
+|        |        |   |
+| ------ | ------ | - |
+| refkey | Refkey |   |
+
+## Returns
+
+string

package/docs/api/functions/untrack.md

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

package/docs/api/functions/useContext.md

@@ -0,0 +1,18 @@
+# useContext
+
+```ts
+import { useContext } from "@alloy-js/core";
+
+
+function useContext<T>(context: ComponentContext<T>): T | undefined;
+```
+
+## Parameters
+
+|         |                      |   |
+| ------- | -------------------- | - |
+| context | ComponentContext\<T> |   |
+
+## Returns
+
+T | undefined

package/docs/api/functions/useFormatOptions.md

@@ -0,0 +1,18 @@
+# useFormatOptions
+
+```ts
+import { useFormatOptions } from "@alloy-js/core";
+
+
+useFormatOptions: (overrides?: Partial<CommonFormatOptions> | undefined) => CommonFormatOptions
+```
+
+## Parameters
+
+|           |                                                     |   |
+| --------- | --------------------------------------------------- | - |
+| overrides | optional Partial\<CommonFormatOptions> \| undefined |   |
+
+## Returns
+
+[CommonFormatOptions](../../types/commonformatoptions/)

package/docs/api/functions/useMemberContext.md

@@ -0,0 +1,17 @@
+# useMemberContext
+
+```ts
+import { useMemberContext } from "@alloy-js/core";
+
+
+function useMemberContext(): MemberContext | undefined;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+[Member context interface](../../contexts/member-context/) | undefined

package/docs/api/functions/useMemberScope.md

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

package/docs/api/functions/writeOutput.md

@@ -0,0 +1,21 @@
+# writeOutput
+
+Write the output from [render](../render/) to the file system.
+
+```ts
+import { writeOutput } from "@alloy-js/core";
+
+
+function writeOutput(output: OutputDirectory, basePath?: string): Promise<void>;
+```
+
+## Parameters
+
+|          |                 |   |
+| -------- | --------------- | - |
+| output   | OutputDirectory |   |
+| basePath | optional string |   |
+
+## Returns
+
+Promise\<void>

package/docs/api/index.md

@@ -0,0 +1,9 @@
+# @alloy-js/core API Reference
+
+- [components](components/index.md) (25 items)
+- [contexts](contexts/index.md) (9 items)
+- [functions](functions/index.md) (103 items)
+- [testing/functions](testing/functions/index.md) (4 items)
+- [testing/types](testing/types/index.md) (2 items)
+- [types](types/index.md) (120 items)
+- [variables](variables/index.md) (9 items)

package/docs/api/testing/functions/createTestWrapper.md

@@ -0,0 +1,70 @@
+# createTestWrapper
+
+Create a reusable test harness for a language package. Returns a `Wrapper` component (wraps content in `<Output>` + `<SourceFile>`) and a `defkey` helper that creates stable namekeys for pre-declaring symbols.
+
+```ts
+import { createTestWrapper } from "@alloy-js/core/testing";
+
+
+function createTestWrapper<SymbolT extends OutputSymbol, ScopeT extends {
+    spaces: any;
+}>(opts: {
+    filePath: string;
+    useScope: () => ScopeT | undefined;
+    makeSymbol: (nk: Namekey, scope: ScopeT) => SymbolT;
+    SourceFile: (props: {
+        path: string;
+        children: Children;
+    }) => any;
+    namePolicy?: NamePolicy<string>;
+    nameConflictResolver?: NameConflictResolver;
+}): TestWrapper;
+```
+
+## Parameters
+
+|      |                                                                                                                                                                                                                                                                   |   |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
+| opts | { filePath: string; useScope: () => ScopeT \| undefined; makeSymbol: (nk: Namekey, scope: ScopeT) => SymbolT; SourceFile: (props: { path: string; children: Children; }) => any; namePolicy?: NamePolicy\<string>; nameConflictResolver?: NameConflictResolver; } |   |
+
+## Returns
+
+TestWrapper
+
+## Remarks
+
+Downstream consumers import and call this from the language package’s `testing/` entrypoint. The `Wrapper` automatically declares symbols created by `defkey` before rendering children, so tests can reference symbols without explicit `<Declaration>` boilerplate.
+
+## Examples
+
+```ts
+// In your language package's testing/ entrypoint:
+import { FileComponent } from "./components/index.js"; // your language package's top-level file component
+import { createTestWrapper, type TestWrapper } from "@alloy-js/core/testing";
+
+export function createMyLangTestWrapper(): TestWrapper {
+  return createTestWrapper({
+    filePath: "test.ext",
+    useScope: useMyLangScope,
+    makeSymbol: (nk, scope) => new MyOutputSymbol(nk, scope),
+    SourceFile: FileComponent,
+  });
+}
+```
+
+```ts
+// Extend your language test factory to accept and forward namePolicy:
+export function createMyLangTestWrapper(namePolicy?: NamePolicy<string>): TestWrapper {
+  return createTestWrapper({ ...langOpts, namePolicy });
+}
+
+// In a name-policy test:
+const { Wrapper } = createMyLangTestWrapper(myNamePolicy);
+const fooKey = namekey("foo"); // namekey(), not defkey — name policy applies
+// namekey() schedules no pre-declaration; the test body must declare the symbol.
+expect(
+  <Wrapper>
+    <MyDeclaration refkey={fooKey} name="foo" />
+  </Wrapper>
+).toRenderTo("FOO");
+```

package/docs/api/testing/functions/d.md

@@ -0,0 +1,21 @@
+# d
+
+Dedented template literal tag. Strips leading/trailing blank lines and removes the common leading whitespace from all lines — useful for multi-line expected output in tests.
+
+```ts
+import { d } from "@alloy-js/core/testing";
+
+
+function d(strings: TemplateStringsArray, ...values: any[]): string;
+```
+
+## Parameters
+
+|         |                      |   |
+| ------- | -------------------- | - |
+| strings | TemplateStringsArray |   |
+| values  | any\[]               |   |
+
+## Returns
+
+string

package/docs/api/testing/functions/dedent.md

@@ -0,0 +1,18 @@
+# dedent
+
+```ts
+import { dedent } from "@alloy-js/core/testing";
+
+
+function dedent(str: string): string;
+```
+
+## Parameters
+
+|     |        |   |
+| --- | ------ | - |
+| str | string |   |
+
+## Returns
+
+string

package/docs/api/testing/functions/index.md

@@ -0,0 +1,6 @@
+# core/testing — functions
+
+- [createTestWrapper](createTestWrapper.md) — Create a reusable test harness for a language package.
+- [d](d.md) — Dedented template literal tag.
+- [dedent](dedent.md) — import { dedent } from "@alloy-js/core/testing";
+- [renderToString](renderToString.md) — Render a JSX element tree to a string.

package/docs/api/testing/functions/renderToString.md

@@ -0,0 +1,20 @@
+# renderToString
+
+Render a JSX element tree to a string. Convenience wrapper combining `renderTree` and `printTree`.
+
+```ts
+import { renderToString } from "@alloy-js/core/testing";
+
+
+function renderToString(element: Children): string;
+```
+
+## Parameters
+
+|         |          |   |
+| ------- | -------- | - |
+| element | Children |   |
+
+## Returns
+
+string

package/docs/api/testing/index.md

@@ -0,0 +1,4 @@
+# @alloy-js/core/testing API Reference
+
+- [functions](functions/index.md) (4 items)
+- [types](types/index.md) (2 items)

package/docs/api/testing/types/TestWrapper.md

@@ -0,0 +1,10 @@
+# TestWrapper
+
+Test harness returned by [createTestWrapper](../../functions/createtestwrapper/).
+
+## Members
+
+|         |                                              |                                                                                                                                                                                                                                                                                                                |
+| ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| defkey  | (name: string) => Namekey                    | Creates a stable [`Namekey`](../../types/Namekey.md) and schedules a pre-declaration inside \[unresolved link]. Call `defkey(name)` before rendering. `Wrapper` renders `<Declaration symbol={...} />` for this name so `<Reference>` to the returned namekey resolves without requiring an explicit `<Declaration>` in the test body.   |
+| Wrapper | (props: { children: Children; }) => Children | JSX wrapper providing Output + a file-level component + language scope context. Name policy is applied only when `namePolicy`/`nameConflictResolver` are passed to [createTestWrapper](../../functions/createtestwrapper/). Pre-declares all namekeys created by \[unresolved link] before rendering children. |

package/docs/api/testing/types/ToRenderToOptions.md

@@ -0,0 +1,24 @@
+# ToRenderToOptions
+
+Print options passed to `toRenderTo` / `toRenderToAsync`. These override the per-[`SourceFile`](../../components/SourceFile.md) print settings for the duration of the assertion, which is useful when forcing line-breaking with a narrow `printWidth` in tests without needing extremely long inputs.
+
+## Members
+
+|            |                  |                                                       |
+| ---------- | ---------------- | ----------------------------------------------------- |
+| printWidth | optional number  | Maximum line width before the formatter wraps output. |
+| tabWidth   | optional number  | Number of spaces per indentation level.               |
+| useTabs    | optional boolean | Use tab characters instead of spaces.                 |
+
+## Example
+
+```ts
+expect(<MyList items={["a", "b", "c"]} />).toRenderTo(
+  `
+  a,
+  b,
+  c
+  `,
+  { printWidth: 10 }
+);
+```

package/docs/api/testing/types/index.md

@@ -0,0 +1,4 @@
+# core/testing — types
+
+- [TestWrapper](TestWrapper.md) — Test harness returned by [createTestWrapper](../../functions/createtestwrapper/).
+- [ToRenderToOptions](ToRenderToOptions.md) — Print options passed to `toRenderTo` / `toRenderToAsync`.

package/docs/api/types/AlignIntrinsicElement.md

@@ -0,0 +1,5 @@
+# AlignIntrinsicElement
+
+```ts
+type AlignIntrinsicElement = IntrinsicElementBase<"align">;
+```

package/docs/api/types/AppendRegionProps.md

@@ -0,0 +1,5 @@
+# AppendRegionProps
+
+```ts
+type AppendRegionProps = AppendRegionPropsWithChildren | AppendRegionPropsWithContent | AppendRegionPropsBase;
+```

package/docs/api/types/BaseListProps.md

@@ -0,0 +1,21 @@
+# BaseListProps
+
+## Members
+
+|                  |                                   |                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| comma            | optional boolean                  | Place a comma between each element                                                                                                                                                                                                                                                                                                                                 |
+| doubleHardline   | optional boolean                  | Place two hardlines between each element                                                                                                                                                                                                                                                                                                                           |
+| ender            | optional [Children](../children/) | Text to place at the end of the list when there is at least one item. If set to true, the joiner is used.                                                                                                                                                                                                                                                          |
+| enderPunctuation | optional boolean                  | Place the join punctuation at the end, without a line break. The punctuation is emitted unconditionally in flat and broken modes. To add trailing punctuation only in broken mode, use `ender` with `<ifBreak>` inside a `<group>` with a non-hardline joiner (e.g. `line`):```tsx
+<group>
+  <List comma line ender={<ifBreak>,</ifBreak>}>...</List>
+</group>
+``` |
+| hardline         | optional boolean                  | Place a hardline (`<hbr />`) between each element                                                                                                                                                                                                                                                                                                                  |
+| joiner           | optional [Children](../children/) | Text to place between each element                                                                                                                                                                                                                                                                                                                                 |
+| line             | optional boolean                  | Place a regular line (`<br />`) between each element                                                                                                                                                                                                                                                                                                               |
+| literalline      | optional boolean                  | Place a literal line (`<lbr />`) between each element                                                                                                                                                                                                                                                                                                              |
+| semicolon        | optional boolean                  | Place a semicolon between each element                                                                                                                                                                                                                                                                                                                             |
+| softline         | optional boolean                  | Place a softline (`<sbr />`) between each element                                                                                                                                                                                                                                                                                                                  |
+| space            | optional boolean                  | Place a space between each element                                                                                                                                                                                                                                                                                                                                 |

package/docs/api/types/BasePartProps.md

@@ -0,0 +1,10 @@
+# BasePartProps
+
+Base props that all language-specific Part components must include. Language packages extend this with additional props.
+
+## Members
+
+|        |                                           |   |
+| ------ | ----------------------------------------- | - |
+| refkey | optional [Refkeyable](../refkeyable/)     |   |
+| symbol | optional [OutputSymbol](../outputsymbol/) |   |

package/docs/api/types/BasicScope.md

@@ -0,0 +1,15 @@
+# BasicScope
+
+BasicScope is a kind of OutputScope that has a single declaration space named `symbols`. It is suitable for use in simple language implementations where there isn’t much in the way of unique scope semantics.
+
+## Members
+
+Extends [OutputScope](../outputscope/)
+
+|                         |                                                                                                                          |   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | - |
+| declarationSpaces       | readonly \[“symbols”]                                                                                                    |   |
+| defaultDeclarationSpace |                                                                                                                          |   |
+| symbolNames             | ReadonlyMap\<string, import(”./output-symbol.js”).[OutputSymbol](../outputsymbol/)>                                      |   |
+| symbols                 | import(”./output-space.js”).[OutputSpace](../outputspace/)                                                               |   |
+| symbolsByRefkey         | ReadonlyMap\<import(”../refkey.js”).[Refkey](../refkey/), import(”./output-symbol.js”).[OutputSymbol](../outputsymbol/)> |   |

package/docs/api/types/BasicSymbol.md

@@ -0,0 +1,18 @@
+# BasicSymbol
+
+BasicSymbol is a kind of OutputSymbol that has instance and static members. It is suitable for use in simple language implementations where there isn’t much in the way of unique symbol semantics.
+
+## Members
+
+Extends [OutputSymbol](../outputsymbol/)
+
+|                 |                                                                        |   |
+| --------------- | ---------------------------------------------------------------------- | - |
+| copy            | () => BasicSymbol                                                      |   |
+| instanceMembers | import(”./output-space.js”).[OutputMemberSpace](../outputmemberspace/) |   |
+| memberSpaces    | string\[]                                                              |   |
+| staticMembers   | import(”./output-space.js”).[OutputMemberSpace](../outputmemberspace/) |   |
+
+## Remarks
+
+Instantiation is done by copying symbols from instance members to static members of the instantiation target.

package/docs/api/types/Binder.md

@@ -0,0 +1,18 @@
+# Binder
+
+The binder tracks all output scopes and symbols. Scopes are nested containers for symbols.
+
+## Members
+
+|                         |                                                                                                                                                                      |                                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| getSymbolForRefkey      | (refkey: Refkeyable) => Ref\<TSymbol \| undefined>                                                                                                                   | Get a ref to the symbol associated with the given refkey. The value of the ref is undefined if the symbol has not been created yet. |
+| nameConflictResolver    | optional [NameConflictResolver](../nameconflictresolver/)                                                                                                            | The name conflict resolver to use for this binder.                                                                                  |
+| notifyScopeCreated      | (scope: OutputScope) => void                                                                                                                                         | Notifies the binder that a scope has been created.                                                                                  |
+| notifySymbolCreated     | (symbol: OutputSymbol) => void                                                                                                                                       | Notifies the binder that a symbol has been created.                                                                                 |
+| notifySymbolDeleted     | (symbol: OutputSymbol) => void                                                                                                                                       | Notifies the binder that a symbol has been deleted.                                                                                 |
+| resolveDeclarationByKey | (currentScope: TScope \| undefined, key: Refkey, options: ResolveDeclarationByKeyOptions\<TScope, TSymbol>) => Ref\<ResolutionResult\<TScope, TSymbol> \| undefined> | Resolve the given refkey in the current scope.                                                                                      |
+
+## Remarks
+
+Symbol information is reactive because in certain situations this data may change. For example, when a symbol becomes conflicted with another symbol, one of the symbol names may change. Ensure that you interact with binder values in a reactive context (i.e. within JSX/code template, or within memo/computed/etc).

package/docs/api/types/BinderOptions.md

@@ -0,0 +1,7 @@
+# BinderOptions
+
+## Members
+
+|                      |                                                           |   |
+| -------------------- | --------------------------------------------------------- | - |
+| nameConflictResolver | optional [NameConflictResolver](../nameconflictresolver/) |   |

package/docs/api/types/BrIntrinsicElement.md

@@ -0,0 +1,5 @@
+# BrIntrinsicElement
+
+```ts
+type BrIntrinsicElement = IntrinsicElementBase<"br">;
+```

package/docs/api/types/BreakParentIntrinsicElement.md

@@ -0,0 +1,5 @@
+# BreakParentIntrinsicElement
+
+```ts
+type BreakParentIntrinsicElement = IntrinsicElementBase<"breakParent">;
+```

package/docs/api/types/Child.md

@@ -0,0 +1,5 @@
+# Child
+
+```ts
+type Child = RenderableObject | RefkeyableObject | string | boolean | number | undefined | null | void | (() => Children) | Ref | Refkey | CustomContext | IntrinsicElement;
+```