@streetui/context 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreetUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @streetui/context
+
+Minimal build-time provider/consumer scoping for the StreetUI DSL. This is **not**
+a re-implementation of React Context and it is **not** a second reactive system —
+it is a tiny synchronous value stack that mirrors how StreetUI builds its
+semantic tree.
+
+```bash
+# part of the StreetUI monorepo — no separate install
+```
+
+---
+
+## Why it exists
+
+StreetUI builds its semantic tree synchronously, top-down, when the DSL builders
+run. A `Context` mirrors that shape exactly: `provide(value, run)` pushes a value
+for the duration of the synchronous `run()` — during which the child DSL builders
+execute and may `consume()` — then pops it again. This lets deeply nested field
+helpers reach a shared form, an i18n instance, a theme, or any other ambient
+value **without prop drilling**, while staying entirely inside the existing
+build pass.
+
+Because `provide()` pops its value as soon as `run()` returns (even if it
+throws), the context holds no subscriptions and leaves no references behind. If
+you need reactivity, put a **signal** into the context — reactivity then belongs
+to that signal and is torn down by the normal node lifecycle when the consuming
+subtree unmounts.
+
+---
+
+## API
+
+```ts
+import { createContext, type Context } from '@streetui/context';
+
+const context = createContext<T>(defaultValue, 'optional.debug.description');
+```
+
+| Member | Description |
+|---|---|
+| `context.provide(value, run)` | Provide `value` to any `consume()` made synchronously inside `run`; returns `run`'s result. |
+| `context.consume()` | Read the **nearest** active provider's value, or `defaultValue` when none is active. |
+| `context.hasProvider()` | True while at least one provider is active. |
+| `context.defaultValue` | The value `consume()` returns with no active provider. |
+| `context.id` | A unique `symbol` identity (handy for debugging/inspection). |
+
+The default value is **required**, so `consume()` always returns a `T` — never
+`undefined` unless `T` itself permits it.
+
+---
+
+## Example — sharing a form down to field helpers
+
+```ts
+import { createContext } from '@streetui/context';
+
+interface FormScope { form: Form<SignupValues>; i18n: AccountI18n; }
+const FormContext = createContext<FormScope | null>(null, 'streetui.account.form');
+
+function textField(scope: ContainerDSL, name: keyof SignupValues & string) {
+  const scoped = FormContext.consume();
+  if (scoped === null) throw new Error('textField must run inside a FormContext provider');
+  const { form, i18n } = scoped;
+  const field = form.field(name);
+  scope.input({ bind: field.value });
+}
+
+// Provider wraps the synchronous builder run:
+page.form('signup', (fb) => {
+  FormContext.provide({ form, i18n }, () => {
+    textField(fb, 'name');
+    textField(fb, 'email');
+    textField(fb, 'password');
+  });
+});
+```
+
+## Nested providers resolve nearest
+
+```ts
+const Theme = createContext('light');
+
+Theme.provide('dark', () => {
+  Theme.consume();                       // 'dark'
+  Theme.provide('high-contrast', () => {
+    Theme.consume();                     // 'high-contrast' (nearest wins)
+  });
+  Theme.consume();                       // 'dark' again — inner value popped
+});
+Theme.consume();                          // 'light' (the default)
+```
+
+---
+
+## Reactive context
+
+The value can be a signal (or an object holding signals). The context stores the
+reference; the signal owns the reactivity:
+
+```ts
+const Locale = createContext(signal('en'));
+
+Locale.provide(signal('fr'), () => {
+  const locale = Locale.consume();       // Signal<string>
+  page.text(locale);                     // reactive — re-renders when the signal changes
+});
+```
+
+Consume only inside a provider's synchronous `run()`. Consuming later (e.g. from
+an async callback that runs after `provide()` has returned) resolves to the
+default, by design — the value has already been popped.

package/dist/index.cjs

@@ -0,0 +1,54 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createContext: () => createContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.ts
+function createContext(defaultValue, description) {
+  const id = Symbol(description ?? "streetui.context");
+  const stack = [];
+  return {
+    id,
+    defaultValue,
+    provide(value, run) {
+      stack.push(value);
+      try {
+        return run();
+      } finally {
+        stack.pop();
+      }
+    },
+    consume() {
+      return stack.length > 0 ? stack[stack.length - 1] : defaultValue;
+    },
+    hasProvider() {
+      return stack.length > 0;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createContext
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/context.ts"],"sourcesContent":["export * from './context.js';\n","/**\n * @streetui/context — build-time provider/consumer scoping.\n *\n * StreetUI builds its semantic tree synchronously, top-down, when the DSL\n * builders run. A `Context` mirrors that shape: `provide(value, run)` pushes a\n * value for the duration of the synchronous `run()` (during which the child\n * DSL builders execute and may `consume()`), then pops it. Consumers resolve\n * the *nearest* enclosing provider, falling back to the context default.\n *\n * This is deliberately NOT a second reactive system. A context value can be a\n * signal (see @streetui/state); reactivity then belongs to that signal and is\n * torn down by the normal node lifecycle when the consuming subtree unmounts —\n * the context itself holds no subscriptions and leaves no refs behind after a\n * `provide()` call returns.\n */\n\nexport interface Context<T> {\n  /** Unique identity for this context (useful for debugging/inspection). */\n  readonly id: symbol;\n  /** The value returned by {@link consume} when no provider is active. */\n  readonly defaultValue: T;\n  /**\n   * Provide `value` to any `consume()` calls made synchronously inside `run`.\n   * The value is popped again as soon as `run` returns (even if it throws),\n   * so nesting resolves to the nearest active provider.\n   */\n  provide<R>(value: T, run: () => R): R;\n  /** Read the nearest active provider's value, or {@link defaultValue}. */\n  consume(): T;\n  /** True while at least one provider is active for this context. */\n  hasProvider(): boolean;\n}\n\n/**\n * Create a typed context with a required default value, so `consume()` always\n * returns a `T` (never `undefined` unless `T` itself permits it).\n */\nexport function createContext<T>(defaultValue: T, description?: string): Context<T> {\n  const id = Symbol(description ?? 'streetui.context');\n  const stack: T[] = [];\n\n  return {\n    id,\n    defaultValue,\n    provide<R>(value: T, run: () => R): R {\n      stack.push(value);\n      try {\n        return run();\n      } finally {\n        stack.pop();\n      }\n    },\n    consume(): T {\n      return stack.length > 0 ? (stack[stack.length - 1] as T) : defaultValue;\n    },\n    hasProvider(): boolean {\n      return stack.length > 0;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACqCO,SAAS,cAAiB,cAAiB,aAAkC;AAClF,QAAM,KAAK,OAAO,eAAe,kBAAkB;AACnD,QAAM,QAAa,CAAC;AAEpB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,QAAW,OAAU,KAAiB;AACpC,YAAM,KAAK,KAAK;AAChB,UAAI;AACF,eAAO,IAAI;AAAA,MACb,UAAE;AACA,cAAM,IAAI;AAAA,MACZ;AAAA,IACF;AAAA,IACA,UAAa;AACX,aAAO,MAAM,SAAS,IAAK,MAAM,MAAM,SAAS,CAAC,IAAU;AAAA,IAC7D;AAAA,IACA,cAAuB;AACrB,aAAO,MAAM,SAAS;AAAA,IACxB;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+/**
+ * @streetui/context — build-time provider/consumer scoping.
+ *
+ * StreetUI builds its semantic tree synchronously, top-down, when the DSL
+ * builders run. A `Context` mirrors that shape: `provide(value, run)` pushes a
+ * value for the duration of the synchronous `run()` (during which the child
+ * DSL builders execute and may `consume()`), then pops it. Consumers resolve
+ * the *nearest* enclosing provider, falling back to the context default.
+ *
+ * This is deliberately NOT a second reactive system. A context value can be a
+ * signal (see @streetui/state); reactivity then belongs to that signal and is
+ * torn down by the normal node lifecycle when the consuming subtree unmounts —
+ * the context itself holds no subscriptions and leaves no refs behind after a
+ * `provide()` call returns.
+ */
+interface Context<T> {
+    /** Unique identity for this context (useful for debugging/inspection). */
+    readonly id: symbol;
+    /** The value returned by {@link consume} when no provider is active. */
+    readonly defaultValue: T;
+    /**
+     * Provide `value` to any `consume()` calls made synchronously inside `run`.
+     * The value is popped again as soon as `run` returns (even if it throws),
+     * so nesting resolves to the nearest active provider.
+     */
+    provide<R>(value: T, run: () => R): R;
+    /** Read the nearest active provider's value, or {@link defaultValue}. */
+    consume(): T;
+    /** True while at least one provider is active for this context. */
+    hasProvider(): boolean;
+}
+/**
+ * Create a typed context with a required default value, so `consume()` always
+ * returns a `T` (never `undefined` unless `T` itself permits it).
+ */
+declare function createContext<T>(defaultValue: T, description?: string): Context<T>;
+
+export { type Context, createContext };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @streetui/context — build-time provider/consumer scoping.
+ *
+ * StreetUI builds its semantic tree synchronously, top-down, when the DSL
+ * builders run. A `Context` mirrors that shape: `provide(value, run)` pushes a
+ * value for the duration of the synchronous `run()` (during which the child
+ * DSL builders execute and may `consume()`), then pops it. Consumers resolve
+ * the *nearest* enclosing provider, falling back to the context default.
+ *
+ * This is deliberately NOT a second reactive system. A context value can be a
+ * signal (see @streetui/state); reactivity then belongs to that signal and is
+ * torn down by the normal node lifecycle when the consuming subtree unmounts —
+ * the context itself holds no subscriptions and leaves no refs behind after a
+ * `provide()` call returns.
+ */
+interface Context<T> {
+    /** Unique identity for this context (useful for debugging/inspection). */
+    readonly id: symbol;
+    /** The value returned by {@link consume} when no provider is active. */
+    readonly defaultValue: T;
+    /**
+     * Provide `value` to any `consume()` calls made synchronously inside `run`.
+     * The value is popped again as soon as `run` returns (even if it throws),
+     * so nesting resolves to the nearest active provider.
+     */
+    provide<R>(value: T, run: () => R): R;
+    /** Read the nearest active provider's value, or {@link defaultValue}. */
+    consume(): T;
+    /** True while at least one provider is active for this context. */
+    hasProvider(): boolean;
+}
+/**
+ * Create a typed context with a required default value, so `consume()` always
+ * returns a `T` (never `undefined` unless `T` itself permits it).
+ */
+declare function createContext<T>(defaultValue: T, description?: string): Context<T>;
+
+export { type Context, createContext };

package/dist/index.js

@@ -0,0 +1,27 @@
+// src/context.ts
+function createContext(defaultValue, description) {
+  const id = Symbol(description ?? "streetui.context");
+  const stack = [];
+  return {
+    id,
+    defaultValue,
+    provide(value, run) {
+      stack.push(value);
+      try {
+        return run();
+      } finally {
+        stack.pop();
+      }
+    },
+    consume() {
+      return stack.length > 0 ? stack[stack.length - 1] : defaultValue;
+    },
+    hasProvider() {
+      return stack.length > 0;
+    }
+  };
+}
+export {
+  createContext
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts"],"sourcesContent":["/**\n * @streetui/context — build-time provider/consumer scoping.\n *\n * StreetUI builds its semantic tree synchronously, top-down, when the DSL\n * builders run. A `Context` mirrors that shape: `provide(value, run)` pushes a\n * value for the duration of the synchronous `run()` (during which the child\n * DSL builders execute and may `consume()`), then pops it. Consumers resolve\n * the *nearest* enclosing provider, falling back to the context default.\n *\n * This is deliberately NOT a second reactive system. A context value can be a\n * signal (see @streetui/state); reactivity then belongs to that signal and is\n * torn down by the normal node lifecycle when the consuming subtree unmounts —\n * the context itself holds no subscriptions and leaves no refs behind after a\n * `provide()` call returns.\n */\n\nexport interface Context<T> {\n  /** Unique identity for this context (useful for debugging/inspection). */\n  readonly id: symbol;\n  /** The value returned by {@link consume} when no provider is active. */\n  readonly defaultValue: T;\n  /**\n   * Provide `value` to any `consume()` calls made synchronously inside `run`.\n   * The value is popped again as soon as `run` returns (even if it throws),\n   * so nesting resolves to the nearest active provider.\n   */\n  provide<R>(value: T, run: () => R): R;\n  /** Read the nearest active provider's value, or {@link defaultValue}. */\n  consume(): T;\n  /** True while at least one provider is active for this context. */\n  hasProvider(): boolean;\n}\n\n/**\n * Create a typed context with a required default value, so `consume()` always\n * returns a `T` (never `undefined` unless `T` itself permits it).\n */\nexport function createContext<T>(defaultValue: T, description?: string): Context<T> {\n  const id = Symbol(description ?? 'streetui.context');\n  const stack: T[] = [];\n\n  return {\n    id,\n    defaultValue,\n    provide<R>(value: T, run: () => R): R {\n      stack.push(value);\n      try {\n        return run();\n      } finally {\n        stack.pop();\n      }\n    },\n    consume(): T {\n      return stack.length > 0 ? (stack[stack.length - 1] as T) : defaultValue;\n    },\n    hasProvider(): boolean {\n      return stack.length > 0;\n    },\n  };\n}\n"],"mappings":";AAqCO,SAAS,cAAiB,cAAiB,aAAkC;AAClF,QAAM,KAAK,OAAO,eAAe,kBAAkB;AACnD,QAAM,QAAa,CAAC;AAEpB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,QAAW,OAAU,KAAiB;AACpC,YAAM,KAAK,KAAK;AAChB,UAAI;AACF,eAAO,IAAI;AAAA,MACb,UAAE;AACA,cAAM,IAAI;AAAA,MACZ;AAAA,IACF;AAAA,IACA,UAAa;AACX,aAAO,MAAM,SAAS,IAAK,MAAM,MAAM,SAAS,CAAC,IAAU;AAAA,IAC7D;AAAA,IACA,cAAuB;AACrB,aAAO,MAAM,SAAS;AAAA,IACxB;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@streetui/context",
+  "version": "1.0.0",
+  "description": "StreetUI context — build-time provider/consumer scoping with nearest-provider resolution",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "tsup": "*",
+    "vitest": "*"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}