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

package/docs/api/components/AppendRegion.md

@@ -0,0 +1,83 @@
+# AppendRegion
+
+## Overload 1
+
+* jsx
+
+  ```tsx
+  import { AppendRegion } from "@alloy-js/core";
+
+
+  <AppendRegion id="string">
+    {children}
+  </AppendRegion>
+  ```
+
+* stc
+
+  ```ts
+  import { AppendRegion } from "@alloy-js/core/stc";
+
+
+  AppendRegion({ id: string }).children(children)
+  ```
+
+### Props
+
+|          |                                   |                                      |
+| -------- | --------------------------------- | ------------------------------------ |
+| children | [Children](../../types/children/) | The content to append to the region. |
+| id       | string                            | The ID of the region.                |
+
+## Overload 2
+
+* jsx
+
+  ```tsx
+  import { AppendRegion } from "@alloy-js/core";
+
+
+  <AppendRegion content={Children} id="string" />
+  ```
+
+* stc
+
+  ```ts
+  import { AppendRegion } from "@alloy-js/core/stc";
+
+
+  AppendRegion({ content: Children, id: string }).children(children)
+  ```
+
+### Props
+
+|         |                                   |                                      |
+| ------- | --------------------------------- | ------------------------------------ |
+| content | [Children](../../types/children/) | The content to append to the region. |
+| id      | string                            | The ID of the region.                |
+
+## Overload 3
+
+* jsx
+
+  ```tsx
+  import { AppendRegion } from "@alloy-js/core";
+
+
+  <AppendRegion id="string" />
+  ```
+
+* stc
+
+  ```ts
+  import { AppendRegion } from "@alloy-js/core/stc";
+
+
+  AppendRegion({ id: string }).children(children)
+  ```
+
+### Props
+
+|    |        |                       |
+| -- | ------ | --------------------- |
+| id | string | The ID of the region. |

package/docs/api/components/Block.md

@@ -0,0 +1,49 @@
+# Block
+
+Create an indented block of source text. The block has `opener` text which is added prior to the block, which defaults to `"{"`, and `closer` text which is added after the block, which defaults to `"}"`.
+
+* jsx
+
+  ```tsx
+  import { Block } from "@alloy-js/core";
+
+
+  <Block closer="string" inline newline opener="string">
+    {children}
+  </Block>
+  ```
+
+* stc
+
+  ```ts
+  import { Block } from "@alloy-js/core/stc";
+
+
+  Block({
+    closer: string,
+    inline: boolean,
+    newline: boolean,
+    opener: string,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                            |                                                                                                                                                                                  |
+| -------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| children | optional [Children](../../types/children/) | The block’s contents                                                                                                                                                             |
+| closer   | optional string                            | The closing punctuation of the block. Defaults to ”}“.                                                                                                                           |
+| inline   | optional boolean                           | If true the block will not indent the content into new lines                                                                                                                     |
+| newline  | optional boolean                           | Whether the block starts on a new line. When true, a hardline is added prior to the block. If `inline` is true, this will only apply if the block is also split due to breaking. |
+| opener   | optional string                            | The opening punctuation of the block. Defaults to ”{”.                                                                                                                           |
+
+## Remarks
+
+When `children` is empty, [`Block`](Block.md) renders as `{}` (opener immediately followed by closer) with no indented content — no explicit empty check is needed before passing children.
+
+## Example
+
+```tsx
+// Safe even when props.members is empty — renders `{}`
+<Block>{props.members}</Block>
+```

package/docs/api/components/CopyFile.md

@@ -0,0 +1,26 @@
+# CopyFile
+
+* jsx
+
+  ```tsx
+  import { CopyFile } from "@alloy-js/core";
+
+
+  <CopyFile path="string" src="string" />
+  ```
+
+* stc
+
+  ```ts
+  import { CopyFile } from "@alloy-js/core/stc";
+
+
+  CopyFile({ path: string, src: string }).children(children)
+  ```
+
+## Props
+
+|      |        |                                                                      |
+| ---- | ------ | -------------------------------------------------------------------- |
+| path | string | The path to write the copy to, relative to the containing directory. |
+| src  | string | The path to the file to copy.                                        |

package/docs/api/components/Declaration.md

@@ -0,0 +1,85 @@
+# Declaration
+
+Declares a symbol in the current scope for this component’s children.
+
+## Overload 1
+
+Create a declaration by providing an already created symbol. The symbol is merely exposed via [Declaration context](../../contexts/declaration-context/).
+
+* jsx
+
+  ```tsx
+  import { Declaration } from "@alloy-js/core";
+
+
+  <Declaration symbol={OutputSymbol}>
+    {children}
+  </Declaration>
+  ```
+
+* stc
+
+  ```ts
+  import { Declaration } from "@alloy-js/core/stc";
+
+
+  Declaration({ symbol: OutputSymbol }).children(children)
+  ```
+
+### Props
+
+|          |                                            |                                                                                             |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| children | optional [Children](../../types/children/) |                                                                                             |
+| symbol   | [OutputSymbol](../../types/outputsymbol/)  | The symbol being declared. When provided, the name, refkey, and metadata props are ignored. |
+
+## Overload 2
+
+Create a declaration by providing a symbol name and optional symbol metadata.
+
+* jsx
+
+  ```tsx
+  import { Declaration } from "@alloy-js/core";
+
+
+  <Declaration
+    metadata={Record<string, unknown>}
+    name={string | Namekey}
+    refkey={Refkey | Refkey[]}
+  >
+    {children}
+  </Declaration>
+  ```
+
+* stc
+
+  ```ts
+  import { Declaration } from "@alloy-js/core/stc";
+
+
+  Declaration({
+    metadata: Record<string, unknown>,
+    name: string | Namekey,
+    refkey: Refkey | Refkey[],
+  }).children(children)
+  ```
+
+### Props
+
+|          |                                                                            |                                                              |
+| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| children | optional [Children](../../types/children/)                                 |                                                              |
+| metadata | optional Record\<string, unknown>                                          | Additional metadata for the declared symbol.                 |
+| name     | string \| [Namekey](../../types/namekey/)                                  | The name of this declaration.                                |
+| refkey   | optional [Refkey](../../types/refkey/) \| [Refkey](../../types/refkey/)\[] | The unique key or array of unique keys for this declaration. |
+
+## Remarks
+
+This component must be called in one of two ways: with a name and an optional refkey, or else passing in the symbol. When called with a name and refkey, a symbol will be created in the current scope (provided by [Scope context](../../contexts/scope-context/)) with that name and refkey.
+
+When called with a symbol, that symbol is merely exposed via [Declaration context](../../contexts/declaration-context/). It is assumed that the caller of this component has created the symbol with the `createSymbol` API on the [Binder context](../../contexts/binder-context/).
+
+## See also
+
+* [Binder context](../../contexts/binder-context/)

package/docs/api/components/For.md

@@ -0,0 +1,91 @@
+# For
+
+The For component iterates over the provided array and invokes the child callback for each item. It can optionally be provided with a `joiner` which is placed between each item, and an `ender` which is placed after the last item when there is at least one item.
+
+* jsx
+
+  ```tsx
+  import { For } from "@alloy-js/core";
+
+
+  <For
+    comma
+    doubleHardline
+    each={T}
+    ender={Children}
+    enderPunctuation
+    hardline
+    joiner={Children}
+    line
+    literalline
+    semicolon
+    skipFalsy
+    softline
+    space
+  >
+    {children}
+  </For>
+  ```
+
+* stc
+
+  ```ts
+  import { For } from "@alloy-js/core/stc";
+
+
+  For({
+    comma: boolean,
+    doubleHardline: boolean,
+    each: T,
+    ender: Children,
+    enderPunctuation: boolean,
+    hardline: boolean,
+    joiner: Children,
+    line: boolean,
+    literalline: boolean,
+    semicolon: boolean,
+    skipFalsy: boolean,
+    softline: boolean,
+    space: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|                  |                                                                                      |                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| children         | (…args: \[…[ForCallbackArgs](../../types/forcallbackargs/)\<T>, index: number]) => U | A function to call for each item.                                                                                                                                                                                                                                                                                                                                  |
+| comma            | optional boolean                                                                     | Place a comma between each element                                                                                                                                                                                                                                                                                                                                 |
+| doubleHardline   | optional boolean                                                                     | Place two hardlines between each element                                                                                                                                                                                                                                                                                                                           |
+| each             | T                                                                                    | The array to iterate over.                                                                                                                                                                                                                                                                                                                                         |
+| ender            | optional [Children](../../types/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](../../types/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                                                                                                                                                                                                                                                                                                                             |
+| skipFalsy        | optional boolean                                                                     | Whether to skip falsy values. By default, falsy values are mapped. However, when mapping children, it is useful to skip falsy values, as it enables omitting list elements via patterns like `{condition && <ListItem />}`.                                                                                                                                        |
+| softline         | optional boolean                                                                     | Place a softline (`<sbr />`) between each element                                                                                                                                                                                                                                                                                                                  |
+| space            | optional boolean                                                                     | Place a space between each element                                                                                                                                                                                                                                                                                                                                 |
+
+## Remarks
+
+When the `each` prop is a reactive (e.g. a reactive array, or ref to an array), [`For`](For.md) will automatically update when the array changes. When doing so, it will attempt to avoid re-rendering items which have not changed. For example, when appending an item to a reactive array, existing items will not be re-rendered. Note that presently the implementation is fairly simple - when making modifications to the middle of an array it likely that every element after the modification will be rerendered.
+
+## Example
+
+```tsx
+const items = ["apple", "pear", "plum"];
+return <For each={items}>
+  {(item) => <>Fruit: {item}</>}
+</For>
+```
+
+## See also
+
+* [mapJoin](../../functions/mapjoin/) for mapping arrays to elements outside of JSX templates.

package/docs/api/components/Indent.md

@@ -0,0 +1,40 @@
+# Indent
+
+Create an indented block of source text. The indented block starts a new line at the new indentation level and, with `trailingBreak`, ends with a new line after restoring the indentation level. The default line break is a hard line break suitable for typical blocks of statements but can be configured.
+
+* jsx
+
+  ```tsx
+  import { Indent } from "@alloy-js/core";
+
+
+  <Indent hardline line nobreak softline trailingBreak>
+    {children}
+  </Indent>
+  ```
+
+* stc
+
+  ```ts
+  import { Indent } from "@alloy-js/core/stc";
+
+
+  Indent({
+    hardline: boolean,
+    line: boolean,
+    nobreak: boolean,
+    softline: boolean,
+    trailingBreak: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|               |                                   |                                                                                                                 |
+| ------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| children      | [Children](../../types/children/) |                                                                                                                 |
+| hardline      | optional boolean                  | Use a hard line (`<hbr />`) to start (and optionally end with `trailingBreak`) the new indentation level.       |
+| line          | optional boolean                  | Use a regular line (`<br />`) to start (and optionally end with `trailingBreak`) the new indentation level.     |
+| nobreak       | optional boolean                  | Don’t include a line break. The new indentation level will start after the first linebreak within the children. |
+| softline      | optional boolean                  | Use a soft line (`<sbr />`) to start (and optionally end with `trailingBreak`) the new indentation level.       |
+| trailingBreak | optional boolean                  | Place the configured line break at the end of the block after restoring the indentation level.                  |

package/docs/api/components/List.md

@@ -0,0 +1,68 @@
+# List
+
+Create a list of children with text between each child. The text to join with is specified by providing either `joiner` children, or providing boolean props for the punctuation and line breaks. The default joiner is no punctuation and a hard break. The `ender` prop can provide text to place at the end of the list when there is at least one child.
+
+* jsx
+
+  ```tsx
+  import { List } from "@alloy-js/core";
+
+
+  <List
+    comma
+    doubleHardline
+    ender={Children}
+    enderPunctuation
+    hardline
+    joiner={Children}
+    line
+    literalline
+    semicolon
+    softline
+    space
+  >
+    {children}
+  </List>
+  ```
+
+* stc
+
+  ```ts
+  import { List } from "@alloy-js/core/stc";
+
+
+  List({
+    comma: boolean,
+    doubleHardline: boolean,
+    ender: Children,
+    enderPunctuation: boolean,
+    hardline: boolean,
+    joiner: Children,
+    line: boolean,
+    literalline: boolean,
+    semicolon: boolean,
+    softline: boolean,
+    space: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|                  |                                            |                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| children         | optional [Children](../../types/children/) |                                                                                                                                                                                                                                                                                                                                                                    |
+| comma            | optional boolean                           | Place a comma between each element                                                                                                                                                                                                                                                                                                                                 |
+| doubleHardline   | optional boolean                           | Place two hardlines between each element                                                                                                                                                                                                                                                                                                                           |
+| ender            | optional [Children](../../types/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](../../types/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/components/MemberDeclaration.md

@@ -0,0 +1,89 @@
+# MemberDeclaration
+
+Declares a symbol in the current member scope for this component’s children.
+
+## Overload 1
+
+Create a member declaration by providing a symbol name and optional symbol metadata.
+
+* jsx
+
+  ```tsx
+  import { MemberDeclaration } from "@alloy-js/core";
+
+
+  <MemberDeclaration
+    metadata={Record<string, unknown>}
+    name={string | Namekey}
+    refkey={Refkey | Refkey[]}
+    static
+  >
+    {children}
+  </MemberDeclaration>
+  ```
+
+* stc
+
+  ```ts
+  import { MemberDeclaration } from "@alloy-js/core/stc";
+
+
+  MemberDeclaration({
+    metadata: Record<string, unknown>,
+    name: string | Namekey,
+    refkey: Refkey | Refkey[],
+    static: boolean,
+  }).children(children)
+  ```
+
+### Props
+
+|          |                                                                            |                                                                                     |
+| -------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| children | optional [Children](../../types/children/)                                 |                                                                                     |
+| metadata | optional Record\<string, unknown>                                          | Additional metadata for the declared symbol.                                        |
+| name     | string \| [Namekey](../../types/namekey/)                                  | The name of this declaration.                                                       |
+| refkey   | optional [Refkey](../../types/refkey/) \| [Refkey](../../types/refkey/)\[] | The refkey or array refkeys for this declaration.                                   |
+| static   | optional boolean                                                           | Whether this is a static member. If not provided, the member is an instance member. |
+
+## Overload 2
+
+Create a declaration by providing an already created symbol. The symbol is merely exposed via [Declaration context](../../contexts/declaration-context/).
+
+* jsx
+
+  ```tsx
+  import { MemberDeclaration } from "@alloy-js/core";
+
+
+  <MemberDeclaration symbol={OutputSymbol}>
+    {children}
+  </MemberDeclaration>
+  ```
+
+* stc
+
+  ```ts
+  import { MemberDeclaration } from "@alloy-js/core/stc";
+
+
+  MemberDeclaration({ symbol: OutputSymbol }).children(children)
+  ```
+
+### Props
+
+|          |                                            |                                                                                             |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| children | optional [Children](../../types/children/) |                                                                                             |
+| symbol   | [OutputSymbol](../../types/outputsymbol/)  | The symbol being declared. When provided, the name, refkey, and metadata props are ignored. |
+
+## Remarks
+
+This component must be called in one of two ways: with a name and an optional refkey, or else passing in the symbol. When called with a name and refkey, a [`BasicSymbol`](../types/BasicSymbol.md) will be created in the current member space. When called with a `name`, the owning scope must be a [`BasicScope`](../types/BasicScope.md); for custom scope/symbol types, pass a pre-created `symbol` instead.
+
+When called with a symbol, that symbol is merely exposed via [MemberDeclaration context](../../contexts/memberdeclaration-context/) (not [Declaration context](../../contexts/declaration-context/)). Use [MemberName](../membername/) (not `<Name />`) to render the declared member’s name.
+
+## See also
+
+* [Binder context](../../contexts/binder-context/)
+* [MemberName](../membername/)

package/docs/api/components/MemberName.md

@@ -0,0 +1,21 @@
+# MemberName
+
+Renders the name of the current member declaration from [MemberDeclaration context](../../contexts/memberdeclaration-context/). Use this inside a [MemberDeclaration](../memberdeclaration/) component instead of `<Name />`, which reads from the top-level [Declaration context](../../contexts/declaration-context/).
+
+* jsx
+
+  ```tsx
+  import { MemberName } from "@alloy-js/core";
+
+
+  <MemberName />
+  ```
+
+* stc
+
+  ```ts
+  import { MemberName } from "@alloy-js/core/stc";
+
+
+  MemberName({ }).children(children)
+  ```

package/docs/api/components/MemberScope.md

@@ -0,0 +1,81 @@
+# MemberScope
+
+Declare a member scope, which is a lexical scope whose symbols are provided by the owner symbol.
+
+## Overload 1
+
+Declare a member scope by providing an already created scope. The scope is exposed via [Scope context](../../contexts/scope-context/).
+
+* jsx
+
+  ```tsx
+  import { MemberScope } from "@alloy-js/core";
+
+
+  <MemberScope value={OutputScope}>
+    {children}
+  </MemberScope>
+  ```
+
+* stc
+
+  ```ts
+  import { MemberScope } from "@alloy-js/core/stc";
+
+
+  MemberScope({ value: OutputScope }).children(children)
+  ```
+
+### Props
+
+|          |                                            |                                                                 |
+| -------- | ------------------------------------------ | --------------------------------------------------------------- |
+| children | optional [Children](../../types/children/) |                                                                 |
+| value    | [OutputScope](../../types/outputscope/)    | The scope to use. If not provided, a new scope will be created. |
+
+## Overload 2
+
+Create a member scope by providing a name and optional metadata.
+
+* jsx
+
+  ```tsx
+  import { MemberScope } from "@alloy-js/core";
+
+
+  <MemberScope
+    metadata={Record<string, unknown>}
+    name="string"
+    ownerSymbol={OutputSymbol}
+  >
+    {children}
+  </MemberScope>
+  ```
+
+* stc
+
+  ```ts
+  import { MemberScope } from "@alloy-js/core/stc";
+
+
+  MemberScope({
+    metadata: Record<string, unknown>,
+    name: string,
+    ownerSymbol: OutputSymbol,
+  }).children(children)
+  ```
+
+### Props
+
+|             |                                            |                                                              |
+| ----------- | ------------------------------------------ | ------------------------------------------------------------ |
+| children    | optional [Children](../../types/children/) |                                                              |
+| metadata    | optional Record\<string, unknown>          | Additional metadata for the scope.                           |
+| name        | optional string                            | The name of this scope.                                      |
+| ownerSymbol | [OutputSymbol](../../types/outputsymbol/)  | The symbol whose members provide the symbols for this scope. |
+
+## Remarks
+
+This is used to create members of a symbol, e.g. for class members and the like. In some languages, this scope may provide symbols which are can be referenced lexically, but in other languages, these members may not be in scope and instead must be referenced via the owner symbol itself.
+
+When called with `name` (without `value`), this delegates to `<Scope>` which creates a [`BasicScope`](../types/BasicScope.md). The same restriction applies: the parent scope must be a [`BasicScope`](../types/BasicScope.md). For custom scope types, create your scope and pass it via the `value` prop.

package/docs/api/components/Name.md

@@ -0,0 +1,19 @@
+# Name
+
+* jsx
+
+  ```tsx
+  import { Name } from "@alloy-js/core";
+
+
+  <Name />
+  ```
+
+* stc
+
+  ```ts
+  import { Name } from "@alloy-js/core/stc";
+
+
+  Name({ }).children(children)
+  ```