@alloy-js/core 0.7.0 → 0.9.0

package/src/tap.ts

@@ -7,21 +7,72 @@ import { useScope } from "./context/scope.js";
 import { SourceFileContext } from "./context/source-file.js";
 import { ComponentDefinition } from "./jsx-runtime.js";
 
+/**
+ * The return value of {@link createTap}, this holds a reference to the tapped
+ * value. It will be undefined until the tapped value is initialized.
+ */
 export interface Tap<T> extends ComponentDefinition {
+  /** Ref for the tapped value */
   ref: ShallowRef<T | undefined>;
 }
 
+/**
+ * A function called when the Tap is rendered.
+ *
+ * @returns The tapped value.
+ */
 export interface Tapper<T> {
   (): T | undefined;
 }
 
-export interface Handler<T> {
+/**
+ * A function that is called when the tapped value is available.
+ */
+export interface TapHandler<T> {
   (value: T): void;
 }
 
+/**
+ * Create a component that when rendered, initializes the tapped value
+ * with the provided callback. This is useful for accessing context
+ * provided by child components inside a parent component.
+ *
+ * @example
+ * ```tsx
+ * import { type Children, computed, createTap } from "@alloy-js/core";
+ *
+ * // context we will tap into
+ * const SomeContext = createContext<string>();
+ *
+ * // a component which provides some specific context
+ * function MyDeclaration(props: { children: Children }) {
+ *   return <SomeContext.Provider value="Hello World">
+ *     {props.children}
+ *   </SomeContext.Provider>;
+ * }
+ *
+ * // a parent component which wants to know about the context set
+ * // by its children
+ * function MySpecialDeclaration() {
+ *   const SomeContextTap = createTap(() => useContext(SomeContext));
+ *
+ *   return <>
+ *     The declaration context is: {SomeContextTap.ref}
+ *     <MyDeclaration>
+ *       <SomeContextTap />
+ *     </MyDeclaration>
+ *   </>
+ * }
+ *
+ * @see {@link createDeclarationTap} for tapping {@link DeclarationContext}.
+ * @see {@link createMemberTap} for tapping {@link MemberDeclarationContext}.
+ * @see {@link createScopeTap} for tapping {@link OutputScope}.
+ * @see {@link createSourceFileTap} for tapping {@link SourceFileContext}.
+ * ```
+ */
 export function createTap<T = unknown>(
   tapper: Tapper<T>,
-  handler?: Handler<T>,
+  handler?: TapHandler<T>,
 ): Tap<T> {
   const signal = shallowRef<T | undefined>(undefined);
   const fn = () => {
@@ -38,31 +89,43 @@ export function createTap<T = unknown>(
   return fn;
 }
 
+/**
+ * Create a tap for {@link DeclarationContext}.
+ */
 export function createDeclarationTap<
   TSymbol extends OutputSymbol = OutputSymbol,
->(handler?: Handler<TSymbol>) {
+>(handler?: TapHandler<TSymbol>) {
   return createTap<TSymbol>(() => {
     return useContext(DeclarationContext) as any;
   }, handler);
 }
 
+/**
+ * Create a tap for {@link MemberDeclarationContext}.
+ */
 export function createMemberTap<TSymbol extends OutputSymbol = OutputSymbol>(
-  handler?: Handler<TSymbol>,
+  handler?: TapHandler<TSymbol>,
 ) {
   return createTap<TSymbol>(() => {
     return useContext(MemberDeclarationContext) as any;
   }, handler);
 }
 
+/**
+ * Create a tap for {@link OutputScope}.
+ */
 export function createScopeTap<TScope extends OutputScope = OutputScope>(
-  handler?: Handler<TScope>,
+  handler?: TapHandler<TScope>,
 ) {
   return createTap<TScope>(() => {
     return useScope() as any;
   }, handler);
 }
 
-export function createSourceFileTap(handler?: Handler<SourceFileContext>) {
+/**
+ * Create a tap for {@link (SourceFileContext:interface)}.
+ */
+export function createSourceFileTap(handler?: TapHandler<SourceFileContext>) {
   return createTap(() => {
     return useContext(SourceFileContext);
   }, handler);

package/src/{utils.ts → utils.tsx}

@@ -12,6 +12,7 @@ import {
   untrack,
 } from "./jsx-runtime.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { BaseListProps } from "./components/List.jsx";
 import { OutputDirectory, OutputFile, render } from "./render.js";
 
 export interface JoinOptions {
@@ -321,3 +322,47 @@ export function traverseOutput(
     }
   }
 }
+
+/**
+ * Convert a list of props to a joiner and ender for use in {@link (mapJoin:1)}.
+ */
+export function baseListPropsToMapJoinArgs(props: BaseListProps): JoinOptions {
+  let joiner, punctuation;
+  if ("joiner" in props) {
+    joiner = props.joiner;
+  } else {
+    punctuation =
+      props.comma ? ","
+      : props.semicolon ? ";"
+      : "";
+
+    joiner = (
+      <>
+        {punctuation}
+        {props.softline ?
+          <sbr />
+        : props.hardline ?
+          <hbr />
+        : props.literalline ?
+          <lbr />
+        : props.line ?
+          <br />
+        : props.space ?
+          <> </>
+        : props.doubleHardline ?
+          <>
+            <hbr />
+            <hbr />
+          </>
+        : <hbr />}
+      </>
+    );
+  }
+
+  const ender =
+    "ender" in props ? props.ender
+    : props.enderPunctuation ? punctuation
+    : undefined;
+
+  return { joiner, ender };
+}