|
| 1 | +/** |
| 2 | + * Component Api — contextual operations for component expansion. |
| 3 | + * |
| 4 | + * One public Api replaces the former dependency container (ExpansionContext) |
| 5 | + * and raw Effection context keys. Context-dependent behavior is installed as |
| 6 | + * scope-local middleware via `Component.around(...)`: |
| 7 | + * |
| 8 | + * - Runtime implementations (document import, modifier execution, component |
| 9 | + * state) install at `{ at: "min" }`. Middleware installed in a nested scope |
| 10 | + * runs before inherited middleware, so a component that installs its own |
| 11 | + * `env` shadows its ancestors without leaking into siblings — install |
| 12 | + * inside `scoped()` for automatic removal. |
| 13 | + * - Caller instrumentation and overrides wrap at the default `"max"`. |
| 14 | + */ |
| 15 | + |
| 16 | +import { createApi } from "@effectionx/context-api"; |
| 17 | +import type { Operation } from "effection"; |
| 18 | +import type { EvalScope } from "@effectionx/scope-eval"; |
| 19 | +import type { |
| 20 | + CodeBlockContext, |
| 21 | + CodeBlockResult, |
| 22 | + ComponentDefinition, |
| 23 | + ErrorSegment, |
| 24 | + EvalEnv, |
| 25 | + FunctionComponentDefinition, |
| 26 | + Modifier, |
| 27 | +} from "./types.ts"; |
| 28 | + |
| 29 | +export interface ComponentApi { |
| 30 | + /** `"__root__"` imports the root document. */ |
| 31 | + importComponent(name: string): Operation<ComponentDefinition | FunctionComponentDefinition>; |
| 32 | + applyModifiers(modifiers: Modifier[], block: CodeBlockContext): Operation<CodeBlockResult>; |
| 33 | + /** |
| 34 | + * Report an ErrorSegment under the ambient error policy. The default |
| 35 | + * returns the segment for rendering; suppressed-documentation scopes |
| 36 | + * install middleware that throws instead (spec §6.9). |
| 37 | + */ |
| 38 | + raise(error: ErrorSegment): Operation<ErrorSegment>; |
| 39 | + env: EvalEnv | undefined; |
| 40 | + evalScope: EvalScope | undefined; |
| 41 | + codeBlock(): Operation<CodeBlockContext>; |
| 42 | + /** Whether the current block runs with persistent resource lifetime. */ |
| 43 | + persistent: boolean; |
| 44 | + /** Render the invoking component's children (optionally a named slot). */ |
| 45 | + content(slot?: string): Operation<string>; |
| 46 | +} |
| 47 | + |
| 48 | +export const Component = createApi<ComponentApi>("Component", { |
| 49 | + // deno-lint-ignore require-yield |
| 50 | + *importComponent(name: string): Operation<ComponentDefinition | FunctionComponentDefinition> { |
| 51 | + throw new Error( |
| 52 | + `Component.importComponent("${name}") has no provider. Install one with ` + |
| 53 | + `Component.around({ importComponent }, { at: "min" }) before expansion.`, |
| 54 | + ); |
| 55 | + }, |
| 56 | + // deno-lint-ignore require-yield |
| 57 | + *applyModifiers(_modifiers: Modifier[], block: CodeBlockContext): Operation<CodeBlockResult> { |
| 58 | + throw new Error( |
| 59 | + `Component.applyModifiers() has no provider for block "${block.blockId}". Install one ` + |
| 60 | + `with Component.around({ applyModifiers }, { at: "min" }) before expansion.`, |
| 61 | + ); |
| 62 | + }, |
| 63 | + // deno-lint-ignore require-yield |
| 64 | + *raise(error: ErrorSegment): Operation<ErrorSegment> { |
| 65 | + return error; |
| 66 | + }, |
| 67 | + env: undefined, |
| 68 | + evalScope: undefined, |
| 69 | + // deno-lint-ignore require-yield |
| 70 | + *codeBlock(): Operation<CodeBlockContext> { |
| 71 | + throw new Error( |
| 72 | + "Component.codeBlock() has no provider: no code block is executing in this scope.", |
| 73 | + ); |
| 74 | + }, |
| 75 | + persistent: false, |
| 76 | + // deno-lint-ignore require-yield |
| 77 | + *content(_slot?: string): Operation<string> { |
| 78 | + throw new Error( |
| 79 | + "Component.content() has no provider: not inside a function component invocation.", |
| 80 | + ); |
| 81 | + }, |
| 82 | +}); |
| 83 | + |
| 84 | +export const { |
| 85 | + importComponent, |
| 86 | + applyModifiers, |
| 87 | + raise, |
| 88 | + env, |
| 89 | + evalScope, |
| 90 | + codeBlock, |
| 91 | + persistent, |
| 92 | + content, |
| 93 | +} = Component.operations; |
0 commit comments