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

package/docs/api/functions/memberRefkey.md

@@ -0,0 +1,27 @@
+# memberRefkey
+
+Create a refkey for an instantiation of a symbol.
+
+```ts
+import { memberRefkey } from "@alloy-js/core";
+
+
+function memberRefkey(base: Refkeyable, ...members: [Refkeyable | string, ...(Refkeyable | string)[]]): MemberRefkey;
+```
+
+## Parameters
+
+|         |                                                     |   |
+| ------- | --------------------------------------------------- | - |
+| base    | Refkeyable                                          |   |
+| members | \[Refkeyable \| string, …(Refkeyable \| string)\[]] |   |
+
+## Returns
+
+[MemberRefkey](../../types/memberrefkey/)
+
+## Remarks
+
+Refkeys for instantiated and copied members are a composite refkey of the owner’s refkey and the member’s refkey. So for example, given a refkey for an instantiation of a class `rk1`, and a refkey for the instance member of that class `rk2`, the refkey for the instantiated static member is `refkey(rk1, rk2)`. This function will return the same refkey given those same parameters.
+
+When a static member symbol `rk3` is owned by another static or instance member symbol (i.e. the outer symbol is itself a member container), the refkey of the instaniated static member is still just the composite of the instantiated variable refkey and the refkey of the inner member `refkey(rk1, rk3)`.

package/docs/api/functions/memo.md

@@ -0,0 +1,29 @@
+# memo
+
+Returns a getter caching the result of `fn`. Re-evaluates when reactive dependencies change. See the [Reactivity docs](../../reactivity.md) for details.
+
+```ts
+import { memo } from "@alloy-js/core";
+
+
+function memo<T>(fn: () => T, equal?: boolean, name?: string): () => T;
+```
+
+## Parameters
+
+|       |                  |   |
+| ----- | ---------------- | - |
+| fn    | () => T          |   |
+| equal | optional boolean |   |
+| name  | optional string  |   |
+
+## Returns
+
+() => T A zero-argument getter returning the cached value.
+
+## Example
+
+```ts
+const fullName = memo(() => `${first.value} ${last.value}`);
+fullName(); // cached; re-evaluates when first or last changes
+```

package/docs/api/functions/mergeProps.md

@@ -0,0 +1,64 @@
+# mergeProps
+
+## Overload 1
+
+```ts
+import { mergeProps } from "@alloy-js/core";
+
+
+function mergeProps<T, U>(source: T, source1: U): T & U;
+```
+
+### Parameters
+
+|         |   |   |
+| ------- | - | - |
+| source  | T |   |
+| source1 | U |   |
+
+### Returns
+
+T & U
+
+## Overload 2
+
+```ts
+import { mergeProps } from "@alloy-js/core";
+
+
+function mergeProps<T, U, V>(source: T, source1: U, source2: V): T & U & V;
+```
+
+### Parameters
+
+|         |   |   |
+| ------- | - | - |
+| source  | T |   |
+| source1 | U |   |
+| source2 | V |   |
+
+### Returns
+
+T & U & V
+
+## Overload 3
+
+```ts
+import { mergeProps } from "@alloy-js/core";
+
+
+function mergeProps<T, U, V, W>(source: T, source1: U, source2: V, source3: W): T & U & V & W;
+```
+
+### Parameters
+
+|         |   |   |
+| ------- | - | - |
+| source  | T |   |
+| source1 | U |   |
+| source2 | V |   |
+| source3 | W |   |
+
+### Returns
+
+T & U & V & W

package/docs/api/functions/moveTakenMembersTo.md

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

package/docs/api/functions/namekey.md

@@ -0,0 +1,41 @@
+# namekey
+
+Create a namekey with the given name. The namekey is a unique refkey that represents a single symbol with the given name and the provided naming-related options.
+
+```ts
+import { namekey } from "@alloy-js/core";
+
+
+function namekey(name: string, options?: NamekeyOptions): Namekey;
+```
+
+## Parameters
+
+|         |                         |   |
+| ------- | ----------------------- | - |
+| name    | string                  |   |
+| options | optional NamekeyOptions |   |
+
+## Options
+
+|                    |                  |   |
+| ------------------ | ---------------- | - |
+| ignoreNameConflict | optional boolean |   |
+| ignoreNamePolicy   | optional boolean |   |
+
+## Returns
+
+[Namekey](../../types/namekey/)
+
+## Example
+
+```tsx
+const myClass = namekey("MyClass");
+
+return <>
+  <ClassDeclaration name={myClass} />
+  {myClass}
+</>
+```
+
+Renders a class and a reference to that class.

package/docs/api/functions/nextReactiveId.md

@@ -0,0 +1,19 @@
+# nextReactiveId
+
+Allocate a unique reactive target ID from the same counter space as ref IDs.
+
+```ts
+import { nextReactiveId } from "@alloy-js/core";
+
+
+function nextReactiveId(): number;
+```
+
+## Parameters
+
+|   |
+| - |
+
+## Returns
+
+number

package/docs/api/functions/notifyContentState.md

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

package/docs/api/functions/onCleanup.md

@@ -0,0 +1,26 @@
+# onCleanup
+
+Register a cleanup function which is called when the current reactive scope is recalculated or disposed. This is useful to clean up any side effects created in the reactive scope.
+
+```ts
+import { onCleanup } from "@alloy-js/core";
+
+
+function onCleanup(fn: Disposable): void;
+```
+
+## Parameters
+
+|    |            |   |
+| -- | ---------- | - |
+| fn | Disposable |   |
+
+## Returns
+
+void
+
+## Remarks
+
+When onCleanup is called inside a component definition, the provided function is called when the component is removed from the tree. This can be useful to clean up any side effects created as a result of rendering the component. For example, if rendering a component creates a symbol, `onCleanup` can be used to remove the symbol when the component is removed from the tree.
+
+When onCleanup is called inside a memo or effect, the function is called when the effect is refreshed (e.g. when a memo or computed recalculates) or disposed (e.g. it is no longer needed because it is attached to a component which was removed).

package/docs/api/functions/printTree.md

@@ -0,0 +1,31 @@
+# printTree
+
+Convert a rendered text tree to a string. Will ensure that the scheduler is empty before printing.
+
+```ts
+import { printTree } from "@alloy-js/core";
+
+
+function printTree(tree: RenderedTextTree, options?: PrintTreeOptions): string;
+```
+
+## Parameters
+
+|         |                           |   |
+| ------- | ------------------------- | - |
+| tree    | RenderedTextTree          |   |
+| options | optional PrintTreeOptions |   |
+
+## Options
+
+|                    |                  |                                                                                |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------ |
+| insertFinalNewLine | optional boolean | If files should end with a final new line.                                     |
+| noFlush            | optional boolean | Skip flushing scheduled jobs before printing.                                  |
+| printWidth         | optional number  | The number of characters the printer will wrap on. Defaults to 100 characters. |
+| tabWidth           | optional number  | The number of spaces to use for indentation. Defaults to 2 spaces.             |
+| useTabs            | optional boolean | Whether to use tabs instead of spaces for indentation. Defaults to false.      |
+
+## Returns
+
+string

package/docs/api/functions/reactivePropertyRefId.md

@@ -0,0 +1,21 @@
+# reactivePropertyRefId
+
+Get a stable ref ID for a property of a reactive object. Each (target, key) pair gets a unique positive ID from the same counter as refs.
+
+```ts
+import { reactivePropertyRefId } from "@alloy-js/core";
+
+
+function reactivePropertyRefId(target: object, key: string | number): number;
+```
+
+## Parameters
+
+|        |                  |   |
+| ------ | ---------------- | - |
+| target | object           |   |
+| key    | string \| number |   |
+
+## Returns
+
+number

package/docs/api/functions/ref.md

@@ -0,0 +1,21 @@
+# ref
+
+```ts
+import { ref } from "@alloy-js/core";
+
+
+function ref<T>(value?: T, options?: {
+    isInfrastructure?: boolean;
+}): Ref<T>;
+```
+
+## Parameters
+
+|         |                                          |   |
+| ------- | ---------------------------------------- | - |
+| value   | optional T                               |   |
+| options | optional { isInfrastructure?: boolean; } |   |
+
+## Returns
+
+Ref\<T>

package/docs/api/functions/refId.md

@@ -0,0 +1,18 @@
+# refId
+
+```ts
+import { refId } from "@alloy-js/core";
+
+
+function refId(ref: Ref<unknown>): number;
+```
+
+## Parameters
+
+|     |               |   |
+| --- | ------------- | - |
+| ref | Ref\<unknown> |   |
+
+## Returns
+
+number

package/docs/api/functions/refkey.md

@@ -0,0 +1,24 @@
+# refkey
+
+Create a refkey for the provided arguments. Passing no arguments returns a fresh refkey that is guaranteed to be unique. Otherwise, the arguments passed will be used to create a refkey for those values. Providing the same arguments will always return the same refkey.
+
+```ts
+import { refkey } from "@alloy-js/core";
+
+
+function refkey(...args: unknown[]): Refkey;
+```
+
+## Parameters
+
+|      |            |   |
+| ---- | ---------- | - |
+| args | unknown\[] |   |
+
+## Returns
+
+[Refkey](../../types/refkey/)
+
+## Remarks
+
+Values are compared using the SameValueZero algorithm, which considers objects the same if they are reference identical, and primitives the same if they are the same value, with the exception of `NaN`, which is always considered equal to other `NaN` values, and `-0`, which is considered identical to `+0`

package/docs/api/functions/render.md

@@ -0,0 +1,31 @@
+# render
+
+Render a component tree to source directories and files. Will ensure that all non-async scheduled jobs are completed before returning. If async jobs are found, an error will be thrown. Use `renderAsync` when asynchronous jobs are expected.
+
+```ts
+import { render } from "@alloy-js/core";
+
+
+function render(children: Children, options?: PrintTreeOptions): OutputDirectory;
+```
+
+## Parameters
+
+|          |                           |   |
+| -------- | ------------------------- | - |
+| children | Children                  |   |
+| options  | optional PrintTreeOptions |   |
+
+## Options
+
+|                    |                  |                                                                                |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------ |
+| insertFinalNewLine | optional boolean | If files should end with a final new line.                                     |
+| noFlush            | optional boolean | Skip flushing scheduled jobs before printing.                                  |
+| printWidth         | optional number  | The number of characters the printer will wrap on. Defaults to 100 characters. |
+| tabWidth           | optional number  | The number of spaces to use for indentation. Defaults to 2 spaces.             |
+| useTabs            | optional boolean | Whether to use tabs instead of spaces for indentation. Defaults to false.      |
+
+## Returns
+
+[OutputDirectory](../../types/outputdirectory/)

package/docs/api/functions/renderAsync.md

@@ -0,0 +1,31 @@
+# renderAsync
+
+Render a component tree to source directories and files. Will ensure that all scheduled jobs are completed before returning.
+
+```ts
+import { renderAsync } from "@alloy-js/core";
+
+
+function renderAsync(children: Children, options?: PrintTreeOptions): Promise<OutputDirectory>;
+```
+
+## Parameters
+
+|          |                           |   |
+| -------- | ------------------------- | - |
+| children | Children                  |   |
+| options  | optional PrintTreeOptions |   |
+
+## Options
+
+|                    |                  |                                                                                |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------ |
+| insertFinalNewLine | optional boolean | If files should end with a final new line.                                     |
+| noFlush            | optional boolean | Skip flushing scheduled jobs before printing.                                  |
+| printWidth         | optional number  | The number of characters the printer will wrap on. Defaults to 100 characters. |
+| tabWidth           | optional number  | The number of spaces to use for indentation. Defaults to 2 spaces.             |
+| useTabs            | optional boolean | Whether to use tabs instead of spaces for indentation. Defaults to false.      |
+
+## Returns
+
+Promise<[OutputDirectory](../../types/outputdirectory/)>

package/docs/api/functions/renderTree.md

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

package/docs/api/functions/reportDiagnostics.md

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

package/docs/api/functions/resetRefIdCounter.md

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

package/docs/api/functions/resolve.md

@@ -0,0 +1,31 @@
+# resolve
+
+Resolve a refkey in the current scope. Returns a Ref for the resolution result. The value of the ref will be undefined if the identifier hasn’t been resolved yet.
+
+```ts
+import { resolve } from "@alloy-js/core";
+
+
+function resolve<TScope extends OutputScope, TSymbol extends OutputSymbol>(refkey: Refkey, options?: ResolveDeclarationByKeyOptions<TScope, TSymbol>): Ref<ResolutionResult<TScope, TSymbol>>;
+```
+
+## Parameters
+
+|         |                                                           |   |
+| ------- | --------------------------------------------------------- | - |
+| refkey  | Refkey                                                    |   |
+| options | optional ResolveDeclarationByKeyOptions\<TScope, TSymbol> |   |
+
+## Options
+
+|                |                                                                          |   |
+| -------------- | ------------------------------------------------------------------------ | - |
+| memberResolver | optional [MemberResolver](../../types/memberresolver/)\<TScope, TSymbol> |   |
+
+## Returns
+
+Ref<[ResolutionResult](../../types/resolutionresult/)\<TScope, TSymbol>>
+
+## 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 resolution result.

package/docs/api/functions/root.md

@@ -0,0 +1,25 @@
+# root
+
+```ts
+import { root } from "@alloy-js/core";
+
+
+function root<T>(fn: (d: Disposable) => T, options?: RootOptions): T;
+```
+
+## Parameters
+
+|         |                      |   |
+| ------- | -------------------- | - |
+| fn      | (d: Disposable) => T |   |
+| options | optional RootOptions |   |
+
+## Options
+
+|                |                                                                  |   |
+| -------------- | ---------------------------------------------------------------- | - |
+| componentOwner | optional [ComponentCreator](../../types/componentcreator/)\<any> |   |
+
+## Returns
+
+T

package/docs/api/functions/shallowReactive.md

@@ -0,0 +1,18 @@
+# shallowReactive
+
+```ts
+import { shallowReactive } from "@alloy-js/core";
+
+
+function shallowReactive<T extends object>(target: T): ShallowReactive<T>;
+```
+
+## Parameters
+
+|        |   |   |
+| ------ | - | - |
+| target | T |   |
+
+## Returns
+
+ShallowReactive\<T>

package/docs/api/functions/shallowRef.md

@@ -0,0 +1,21 @@
+# shallowRef
+
+```ts
+import { shallowRef } from "@alloy-js/core";
+
+
+function shallowRef<T>(value?: T, options?: {
+    label?: string;
+}): Ref<T>;
+```
+
+## Parameters
+
+|         |                              |   |
+| ------- | ---------------------------- | - |
+| value   | optional T                   |   |
+| options | optional { label?: string; } |   |
+
+## Returns
+
+Ref\<T>

package/docs/api/functions/sourceFilesForTree.md

@@ -0,0 +1,31 @@
+# sourceFilesForTree
+
+Convert a rendered text tree to source directories and files. Will ensure that all scheduled jobs are completed before returning.
+
+```ts
+import { sourceFilesForTree } from "@alloy-js/core";
+
+
+function sourceFilesForTree(tree: RenderedTextTree, options?: PrintTreeOptions): OutputDirectory;
+```
+
+## Parameters
+
+|         |                           |   |
+| ------- | ------------------------- | - |
+| tree    | RenderedTextTree          |   |
+| options | optional PrintTreeOptions |   |
+
+## Options
+
+|                    |                  |                                                                                |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------ |
+| insertFinalNewLine | optional boolean | If files should end with a final new line.                                     |
+| noFlush            | optional boolean | Skip flushing scheduled jobs before printing.                                  |
+| printWidth         | optional number  | The number of characters the printer will wrap on. Defaults to 100 characters. |
+| tabWidth           | optional number  | The number of spaces to use for indentation. Defaults to 2 spaces.             |
+| useTabs            | optional boolean | Whether to use tabs instead of spaces for indentation. Defaults to false.      |
+
+## Returns
+
+[OutputDirectory](../../types/outputdirectory/)

package/docs/api/functions/splitProps.md

@@ -0,0 +1,19 @@
+# splitProps
+
+```ts
+import { splitProps } from "@alloy-js/core";
+
+
+function splitProps<T extends Record<any, any>, K extends [readonly (keyof T)[], ...(readonly (keyof T)[])[]]>(props: T, ...keys: K): SplitProps<T, K>;
+```
+
+## Parameters
+
+|       |   |   |
+| ----- | - | - |
+| props | T |   |
+| keys  | K |   |
+
+## Returns
+
+[SplitProps](../../types/splitprops/)\<T, K>

package/docs/api/functions/stc.md

@@ -0,0 +1,18 @@
+# stc
+
+```ts
+import { stc } from "@alloy-js/core";
+
+
+function stc<T extends {}>(Component: ComponentDefinition<T>): StcSignature<T>;
+```
+
+## Parameters
+
+|           |                         |   |
+| --------- | ----------------------- | - |
+| Component | ComponentDefinition\<T> |   |
+
+## Returns
+
+[StcSignature](../../types/stcsignature/)\<T>

package/docs/api/functions/sti.md

@@ -0,0 +1,18 @@
+# sti
+
+```ts
+import { sti } from "@alloy-js/core";
+
+
+function sti<T extends keyof IntrinsicElements>(name: T): StiSignature<T>;
+```
+
+## Parameters
+
+|      |   |   |
+| ---- | - | - |
+| name | T |   |
+
+## Returns
+
+[StiSignature](../../types/stisignature/)\<T>