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

package/docs/api/components/Output.md

@@ -0,0 +1,62 @@
+# Output
+
+This component is the root component for all your emitted output. Place your various [SourceDirectory](../sourcedirectory/) and [SourceFile](../sourcefile/) components inside [`Output`](Output.md) to create directories and files in your output directory.
+
+* jsx
+
+  ```tsx
+  import { Output } from "@alloy-js/core";
+
+
+  <Output
+    basePath="string"
+    externals={SymbolCreator[]}
+    insertFinalNewLine
+    nameConflictResolver={NameConflictResolver}
+    namePolicy={NamePolicy<string>}
+    noFlush
+    printWidth={number}
+    tabWidth={number}
+    useTabs
+  >
+    {children}
+  </Output>
+  ```
+
+* stc
+
+  ```ts
+  import { Output } from "@alloy-js/core/stc";
+
+
+  Output({
+    basePath: string,
+    externals: SymbolCreator[],
+    insertFinalNewLine: boolean,
+    nameConflictResolver: NameConflictResolver,
+    namePolicy: NamePolicy<string>,
+    noFlush: boolean,
+    printWidth: number,
+    tabWidth: number,
+    useTabs: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|                      |                                                                    |                                                                                |
+| -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| basePath             | optional string                                                    | The base path for the output contents. Defaults to ”.“                         |
+| children             | optional [Children](../../types/children/)                         |                                                                                |
+| externals            | optional [SymbolCreator](../../types/symbolcreator/)\[]            | External libraries whose symbols should be available for reference.            |
+| insertFinalNewLine   | optional boolean                                                   | If files should end with a final new line.                                     |
+| nameConflictResolver | optional [NameConflictResolver](../../types/nameconflictresolver/) | Policy for handling multiple symbols declared with the same name.              |
+| namePolicy           | optional [NamePolicy](../../types/namepolicy/)\<string>            | Name policy to use for this output.                                            |
+| 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.      |
+
+## See also
+
+* [NamePolicy context](../../contexts/namepolicy-context/)

package/docs/api/components/Prose.md

@@ -0,0 +1,29 @@
+# Prose
+
+Create a block of text which will break once a word exceeds the configured line width. The children are expected to be strings, and a is added between each word.
+
+* jsx
+
+  ```tsx
+  import { Prose } from "@alloy-js/core";
+
+
+  <Prose >
+    {children}
+  </Prose>
+  ```
+
+* stc
+
+  ```ts
+  import { Prose } from "@alloy-js/core/stc";
+
+
+  Prose({  }).children(children)
+  ```
+
+## Props
+
+|          |                                   |   |
+| -------- | --------------------------------- | - |
+| children | [Children](../../types/children/) |   |

package/docs/api/components/ReferenceOrContent.md

@@ -0,0 +1,28 @@
+# ReferenceOrContent
+
+* jsx
+
+  ```tsx
+  import { ReferenceOrContent } from "@alloy-js/core";
+
+
+  <ReferenceOrContent refkey={Refkey}>
+    {children}
+  </ReferenceOrContent>
+  ```
+
+* stc
+
+  ```ts
+  import { ReferenceOrContent } from "@alloy-js/core/stc";
+
+
+  ReferenceOrContent({ refkey: Refkey }).children(children)
+  ```
+
+## Props
+
+|          |                                   |   |
+| -------- | --------------------------------- | - |
+| children | [Children](../../types/children/) |   |
+| refkey   | [Refkey](../../types/refkey/)     |   |

package/docs/api/components/Scope.md

@@ -0,0 +1,83 @@
+# Scope
+
+Declare a scope for this component’s children. Any symbols and scopes declared in the children of this component will be in this scope.
+
+## Overload 1
+
+Declare a scope by providing an already created scope. The scope is merely exposed via [Scope context](../../contexts/scope-context/).
+
+* jsx
+
+  ```tsx
+  import { Scope } from "@alloy-js/core";
+
+
+  <Scope value={OutputScope}>
+    {children}
+  </Scope>
+  ```
+
+* stc
+
+  ```ts
+  import { Scope } from "@alloy-js/core/stc";
+
+
+  Scope({ 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 scope by providing a name and optional metadata.
+
+* jsx
+
+  ```tsx
+  import { Scope } from "@alloy-js/core";
+
+
+  <Scope
+    metadata={Record<string, unknown>}
+    name="string"
+    ownerSymbol={OutputSymbol}
+  >
+    {children}
+  </Scope>
+  ```
+
+* stc
+
+  ```ts
+  import { Scope } from "@alloy-js/core/stc";
+
+
+  Scope({
+    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 | optional [OutputSymbol](../../types/outputsymbol/) | Create a member scope with the owner symbol providing the in-scope symbols. |
+
+## Remarks
+
+When called with `name` (without `value`), this creates a [`BasicScope`](../types/BasicScope.md). The parent scope must also be a [`BasicScope`](../types/BasicScope.md); for custom scope types, create your scope and pass it via the `value` prop instead.
+
+## See also
+
+* [Scope context](../../contexts/scope-context/)

package/docs/api/components/Show.md

@@ -0,0 +1,32 @@
+# Show
+
+* jsx
+
+  ```tsx
+  import { Show } from "@alloy-js/core";
+
+
+  <Show fallback={Children} when={boolean | undefined | null}>
+    {children}
+  </Show>
+  ```
+
+* stc
+
+  ```ts
+  import { Show } from "@alloy-js/core/stc";
+
+
+  Show({
+    fallback: Children,
+    when: boolean | undefined | null,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                            |   |
+| -------- | ------------------------------------------ | - |
+| children | [Children](../../types/children/)          |   |
+| fallback | optional [Children](../../types/children/) |   |
+| when     | boolean \| undefined \| null               |   |

package/docs/api/components/SourceDirectory.md

@@ -0,0 +1,28 @@
+# SourceDirectory
+
+* jsx
+
+  ```tsx
+  import { SourceDirectory } from "@alloy-js/core";
+
+
+  <SourceDirectory path="string">
+    {children}
+  </SourceDirectory>
+  ```
+
+* stc
+
+  ```ts
+  import { SourceDirectory } from "@alloy-js/core/stc";
+
+
+  SourceDirectory({ path: string }).children(children)
+  ```
+
+## Props
+
+|          |                                            |   |
+| -------- | ------------------------------------------ | - |
+| children | optional [Children](../../types/children/) |   |
+| path     | string                                     |   |

package/docs/api/components/SourceFile.md

@@ -0,0 +1,60 @@
+# SourceFile
+
+* jsx
+
+  ```tsx
+  import { SourceFile } from "@alloy-js/core";
+
+
+  <SourceFile
+    filetype="string"
+    header={Children}
+    insertFinalNewLine
+    noFlush
+    path="string"
+    printWidth={number}
+    reference={ComponentDefinition<{
+            refkey: Refkey;
+        }>}
+    tabWidth={number}
+    useTabs
+  >
+    {children}
+  </SourceFile>
+  ```
+
+* stc
+
+  ```ts
+  import { SourceFile } from "@alloy-js/core/stc";
+
+
+  SourceFile({
+    filetype: string,
+    header: Children,
+    insertFinalNewLine: boolean,
+    noFlush: boolean,
+    path: string,
+    printWidth: number,
+    reference: ComponentDefinition<{
+            refkey: Refkey;
+        }>,
+    tabWidth: number,
+    useTabs: boolean,
+  }).children(children)
+  ```
+
+## Props
+
+|                    |                                                                                                              |                                                                                                                                                                                                                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| children           | optional [Children](../../types/children/)                                                                   |                                                                                                                                                                                                                                                                                                  |
+| filetype           | string                                                                                                       | The type of contents in this file. This is a metadata hint only. It does not trigger formatting or content processing. The value is forwarded to debug tooling and the [`ContentOutputFile`](../types/ContentOutputFile.md) output metadata.                                                                                      |
+| header             | optional [Children](../../types/children/)                                                                   | Content rendered before the file body, separated from it by a hard line break. The separator is emitted whenever `header` is not `undefined` — including when it is an empty string or a component that renders nothing. To suppress both the header and the separator, omit this prop entirely. |
+| insertFinalNewLine | optional boolean                                                                                             | If files should end with a final new line.                                                                                                                                                                                                                                                       |
+| noFlush            | optional boolean                                                                                             | Skip flushing scheduled jobs before printing.                                                                                                                                                                                                                                                    |
+| path               | string                                                                                                       | The path of this file relative to its parent directory                                                                                                                                                                                                                                           |
+| printWidth         | optional number                                                                                              | The number of characters the printer will wrap on. Defaults to 100 characters.                                                                                                                                                                                                                   |
+| reference          | optional [ComponentDefinition](../../types/componentdefinition/)<{ refkey: [Refkey](../../types/refkey/); }> | The component to use to render refkeys references within the file’s contents.                                                                                                                                                                                                                    |
+| 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.                                                                                                                                                                                                                        |

package/docs/api/components/StatementList.md

@@ -0,0 +1,29 @@
+# StatementList
+
+Join child elements with semicolons and hardlines.
+
+* jsx
+
+  ```tsx
+  import { StatementList } from "@alloy-js/core";
+
+
+  <StatementList >
+    {children}
+  </StatementList>
+  ```
+
+* stc
+
+  ```ts
+  import { StatementList } from "@alloy-js/core/stc";
+
+
+  StatementList({  }).children(children)
+  ```
+
+## Props
+
+|          |                                   |   |
+| -------- | --------------------------------- | - |
+| children | [Children](../../types/children/) |   |

package/docs/api/components/Switch.md

@@ -0,0 +1,42 @@
+# Switch
+
+Conditionally render blocks of content based on the `when` prop of nested [Match](../../variables/match/) components.
+
+* jsx
+
+  ```tsx
+  import { Switch } from "@alloy-js/core";
+
+
+  <Switch >
+    {children}
+  </Switch>
+  ```
+
+* stc
+
+  ```ts
+  import { Switch } from "@alloy-js/core/stc";
+
+
+  Switch({  }).children(children)
+  ```
+
+## Props
+
+|          |                                   |   |
+| -------- | --------------------------------- | - |
+| children | [Children](../../types/children/) |   |
+
+## Example
+
+```tsx
+<Switch>
+  <Match when={someCondition}>
+    <div>Condition met!</div>
+  </Match>
+  <Match else>
+    <div>Condition not met!</div>
+  </Match>
+</Switch>
+```

package/docs/api/components/TemplateFile.md

@@ -0,0 +1,71 @@
+# TemplateFile
+
+A component that reads a template file and replaces variable placeholders with actual values.
+
+Template files can contain variable placeholders in the format `{{ variable_name }}` which will be replaced with values from [`TemplateVariable`](TemplateVariable.md) children components. Whitespace around variable names is ignored, so `{{ name }}`, `{{name}}`, and `{{ name }}` are all equivalent.
+
+* jsx
+
+  ```tsx
+  import { TemplateFile } from "@alloy-js/core";
+
+
+  <TemplateFile path="string" src="string">
+    {children}
+  </TemplateFile>
+  ```
+
+* stc
+
+  ```ts
+  import { TemplateFile } from "@alloy-js/core/stc";
+
+
+  TemplateFile({ path: string, src: string }).children(children)
+  ```
+
+## Props
+
+|          |                                            |                                             |
+| -------- | ------------------------------------------ | ------------------------------------------- |
+| children | optional [Children](../../types/children/) | Template variable children components.      |
+| path     | string                                     | The path to write the compiled template to. |
+| src      | string                                     | The file path of the template.              |
+
+## Examples
+
+Basic usage with template variables:
+
+```tsx
+// Template file content (greeting.txt):
+// "Hello {{ name }}! You are {{ age }} years old."
+
+<TemplateFile src="greeting.txt" path="output.txt">
+  <TemplateVariable name="name" value="John" />
+  <TemplateVariable name="age" value="25" />
+</TemplateFile>
+```
+
+Using children instead of value prop:
+
+```tsx
+// Template file content (welcome.txt):
+// "Welcome {{ greeting }}!"
+
+<TemplateFile src="welcome.txt" path="output.txt">
+  <TemplateVariable name="greeting">Hello World</TemplateVariable>
+</TemplateFile>
+```
+
+Complex template with multiple variables:
+
+```tsx
+// Template file content (profile.txt):
+// "Name: {{ name }}\nAge: {{ age }}\nLocation: {{ location }}"
+
+<TemplateFile src="profile.txt" path="profile-output.txt">
+  <TemplateVariable name="name" value="Alice" />
+  <TemplateVariable name="age">30</TemplateVariable>
+  <TemplateVariable name="location" value="New York" />
+</TemplateFile>
+```

package/docs/api/components/TemplateVariable.md

@@ -0,0 +1,57 @@
+# TemplateVariable
+
+## Overload 1
+
+* jsx
+
+  ```tsx
+  import { TemplateVariable } from "@alloy-js/core";
+
+
+  <TemplateVariable name="string">
+    {children}
+  </TemplateVariable>
+  ```
+
+* stc
+
+  ```ts
+  import { TemplateVariable } from "@alloy-js/core/stc";
+
+
+  TemplateVariable({ name: string }).children(children)
+  ```
+
+### Props
+
+|          |                                   |                            |
+| -------- | --------------------------------- | -------------------------- |
+| children | [Children](../../types/children/) | The value of the variable. |
+| name     | string                            | The name of the variable.  |
+
+## Overload 2
+
+* jsx
+
+  ```tsx
+  import { TemplateVariable } from "@alloy-js/core";
+
+
+  <TemplateVariable name="string" value="string" />
+  ```
+
+* stc
+
+  ```ts
+  import { TemplateVariable } from "@alloy-js/core/stc";
+
+
+  TemplateVariable({ name: string, value: string }).children(children)
+  ```
+
+### Props
+
+|       |        |                            |
+| ----- | ------ | -------------------------- |
+| name  | string | The name of the variable.  |
+| value | string | The value of the variable. |

package/docs/api/components/UpdateFile.md

@@ -0,0 +1,56 @@
+# UpdateFile
+
+A component for updating existing files or initializing new files.
+
+This component allows you to read the current contents of a file and generate new content based on those contents. If the file doesn’t exist, it can use default content from either a file path or inline content.
+
+Props for the UpdateFile component.
+
+* jsx
+
+  ```tsx
+  import { UpdateFile } from "@alloy-js/core";
+
+
+  <UpdateFile
+    defaultContent={Children}
+    defaultContentPath="string"
+    path="string"
+  >
+    {children}
+  </UpdateFile>
+  ```
+
+* stc
+
+  ```ts
+  import { UpdateFile } from "@alloy-js/core/stc";
+
+
+  UpdateFile({
+    defaultContent: Children,
+    defaultContentPath: string,
+    path: string,
+  }).children(children)
+  ```
+
+## Props
+
+|                    |                                                                        |                                                                                              |
+| ------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| children           | (currentContents: string \| null) => [Children](../../types/children/) | Function that receives the current file contents and returns the new content                 |
+| defaultContent     | optional [Children](../../types/children/)                             | Optional default content to use when the target file doesn’t exist                           |
+| defaultContentPath | optional string                                                        | Optional path to a file containing default content to use when the target file doesn’t exist |
+| path               | string                                                                 | The relative path to the file to update or create                                            |
+
+## Example
+
+```tsx
+<UpdateFile path="config.json" defaultContent="{}">
+  {(currentContents) => {
+    const config = currentContents ? JSON.parse(currentContents) : {};
+    config.newProperty = "value";
+    return JSON.stringify(config, null, 2);
+  }}
+</UpdateFile>
+```

package/docs/api/components/Wrap.md

@@ -0,0 +1,40 @@
+# Wrap
+
+Conditionally wrap the children of this component with the component given to `with` and passing `props` to it.
+
+* jsx
+
+  ```tsx
+  import { Wrap } from "@alloy-js/core";
+
+
+  <Wrap
+    props={Omit<TProps, "children">}
+    when
+    with={ComponentDefinition<TProps>}
+  >
+    {children}
+  </Wrap>
+  ```
+
+* stc
+
+  ```ts
+  import { Wrap } from "@alloy-js/core/stc";
+
+
+  Wrap({
+    props: Omit<TProps, "children">,
+    when: boolean,
+    with: ComponentDefinition<TProps>,
+  }).children(children)
+  ```
+
+## Props
+
+|          |                                                                  |                                                                                                                      |
+| -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| children | [Children](../../types/children/)                                | Children to be wrapped.                                                                                              |
+| props    | optional Omit\<TProps, “children”>                               | Props to pass to the wrapper component.                                                                              |
+| when     | boolean                                                          | When true, the children will be wrapped with the provided component. Otherwise, the children will be rendered as is. |
+| with     | [ComponentDefinition](../../types/componentdefinition/)\<TProps> | Component to be used for wrapping.                                                                                   |