@barefootjs/shared 0.33.2 → 0.33.3

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export { BF_SCOPE, BF_SLOT, BF_HOST, BF_AT, BF_ROOT, BF_PROPS, BF_COND, BF_ITEM, BF_PORTAL_OWNER, BF_PORTAL_ID, BF_PORTAL_PLACEHOLDER, BF_PARENT_OWNED_PREFIX, BF_SCOPE_COMMENT_PREFIX, BF_SCOPE_COMMENT_END_PREFIX, BF_LOOP_START, BF_LOOP_END, BF_LOOP_ITEM, loopItemMarker, loopStartMarker, loopEndMarker, BF_KEY, BF_KEY_PREFIX, BF_PLACEHOLDER, BF_ASYNC, BF_ASYNC_RESOLVE, BF_REGION, BF_PARENT_SCOPE_PLACEHOLDER, BF_SEAM_HYDRATE, BF_SEAM_HYDRATE_WITHIN, BF_SEAM_DISPOSE_WITHIN, BF_SEAM_PUSH_SEARCH, BF_SEAM_NAV_SEARCH, } from './markers.ts';
+export { BF_SCOPE, BF_SLOT, BF_HOST, BF_AT, BF_ROOT, BF_PROPS, BF_COND, BF_ITEM, BF_PORTAL_OWNER, BF_PORTAL_ID, BF_PORTAL_PLACEHOLDER, BF_PARENT_OWNED_PREFIX, BF_SCOPE_COMMENT_PREFIX, BF_SCOPE_COMMENT_END_PREFIX, BF_LOOP_START, BF_LOOP_END, BF_LOOP_ITEM, loopItemMarker, loopStartMarker, loopEndMarker, BF_KEY, BF_KEY_PREFIX, keyAttrName, BF_PLACEHOLDER, BF_ASYNC, BF_ASYNC_RESOLVE, BF_REGION, BF_PARENT_SCOPE_PLACEHOLDER, BF_SEAM_HYDRATE, BF_SEAM_HYDRATE_WITHIN, BF_SEAM_DISPOSE_WITHIN, BF_SEAM_PUSH_SEARCH, BF_SEAM_NAV_SEARCH, } from './markers.ts';
 export { classifyDOMProp, toHTMLAttrName, toHTMLAttrNameRuntime, isBooleanAttr, isEventProp, BOOLEAN_ATTRS, } from './dom-prop.ts';
 export type { DOMPropKind, DOMPropClassification } from './dom-prop.ts';
 export { decodeEntities, escapeHtml } from './html-entities.ts';
+export { resolveJsxChildrenProp } from './jsx-children-prop.ts';
+export type { ChildrenSlotPropLike } from './jsx-children-prop.ts';
 export type { ProfilerEvent, ProfilerEventType, ProfilerSubscriberKind, } from './profiler-events.ts';

package/dist/index.js

@@ -27,6 +27,9 @@ function loopEndMarker(markerId) {
 }
 var BF_KEY = "data-key";
 var BF_KEY_PREFIX = "data-key-";
+function keyAttrName(loopDepth) {
+  return loopDepth > 0 ? `${BF_KEY_PREFIX}${loopDepth}` : BF_KEY;
+}
 var BF_PLACEHOLDER = "data-bf-ph";
 var BF_ASYNC = "bf-async";
 var BF_ASYNC_RESOLVE = "bf-async-resolve";
@@ -335,12 +338,23 @@ function decodeEntities(text) {
 function escapeHtml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+// src/jsx-children-prop.ts
+function resolveJsxChildrenProp(props) {
+  const prop = props.find((p) => p.name === "children");
+  if (!prop)
+    return [];
+  if (prop.value.kind !== "jsx-children")
+    return [];
+  return prop.value.children ?? [];
+}
 export {
   toHTMLAttrNameRuntime,
   toHTMLAttrName,
+  resolveJsxChildrenProp,
   loopStartMarker,
   loopItemMarker,
   loopEndMarker,
+  keyAttrName,
   isEventProp,
   isBooleanAttr,
   escapeHtml,

package/dist/jsx-children-prop.d.ts

@@ -0,0 +1,52 @@
+/**
+ * BarefootJS — reserved `children` JSX-prop resolver
+ *
+ * Answers one question for every adapter: "which prop on this component
+ * call supplies the reserved `children` slot?" Before this module existed,
+ * two independently-maintained answers had drifted apart (issue #2773):
+ *
+ * - The seven DSL adapters (Blade/ERB/Jinja/Mojolicious/minijinja/Twig/
+ *   Xslate) each carried a byte-identical private copy of this function in
+ *   their own `lib/ir-scope.ts`, matching on the prop NAMED `children`.
+ * - The Go template adapter's `jsxChildrenPropNodes` answered a different
+ *   question: the FIRST prop of ANY name carrying a `jsx-children`
+ *   payload. For a component with an earlier JSX-element prop (e.g.
+ *   `header={<span/>}`) and no `children` prop at all, that silently
+ *   backfilled `.Children` with the `header` payload — and when a
+ *   `children` prop WAS also given, it lost `children`'s payload entirely
+ *   in favor of the earlier prop's.
+ *
+ * Hono, the reference adapter, resolves `children` by name — ordinary JSX
+ * semantics: `<Card header={<A/>} children={<B/>} />` binds `header` and
+ * `children` to two separate props, exactly as `React.createElement`
+ * would. The DSL adapters already agreed with Hono; this module makes
+ * their shared answer the ONLY implementation, so Go template (and any
+ * future adapter) calls it instead of growing its own copy that can
+ * re-diverge.
+ *
+ * Generic and structurally typed rather than importing `IRProp`/`IRNode`
+ * from `@barefootjs/jsx`: `@barefootjs/jsx` itself depends on
+ * `@barefootjs/shared`, so importing the other direction would be a
+ * dependency cycle. Callers pass their real IR prop array and get back a
+ * concretely-typed node array — no cast, no parallel type declaration to
+ * keep in sync with `@barefootjs/jsx`'s `AttrValue` union.
+ */
+/** Structural shape of an `AttrValue`-like prop value, generic over the node type a `jsx-children` payload carries. */
+interface JsxChildrenAttrValueLike<TNode> {
+    kind: string;
+    children?: TNode[];
+}
+/** Structural shape of one IR prop, generic over the node type. */
+export interface ChildrenSlotPropLike<TNode> {
+    name: string;
+    value: JsxChildrenAttrValueLike<TNode>;
+}
+/**
+ * Find the prop literally named `children` and, if its value carries a
+ * `jsx-children` payload, return that payload's nodes. Returns `[]` when
+ * no `children` prop exists, or when one exists but is not a resolved
+ * JSX-children payload (e.g. an ordinary expression prop that merely
+ * happens to be named `children`).
+ */
+export declare function resolveJsxChildrenProp<TNode>(props: ReadonlyArray<ChildrenSlotPropLike<TNode>>): TNode[];
+export {};

package/dist/markers.d.ts

@@ -118,6 +118,21 @@ export declare function loopEndMarker(markerId: string): string;
 export declare const BF_KEY = "data-key";
 /** Nested loop key attribute prefix: `data-key-1`, `data-key-2` */
 export declare const BF_KEY_PREFIX = "data-key-";
+/**
+ * The row-key attribute NAME for a `.map()` nested `loopDepth` levels deep
+ * (0 = outermost): `data-key` at depth 0, `data-key-N` at depth N > 0.
+ *
+ * Single source of truth for a derivation that used to be re-implemented at
+ * every emission site — the CSR codegen path (`ir-to-client-js/utils.ts`,
+ * pre-existing re-export), IR-build time (`IRElement.keyAttr`,
+ * `jsx-to-ir.ts`), and — before that consolidation — independently again by
+ * each of the 9 SSR adapters (a mutable stack in Hono, a `currentLoopKeyDepth`
+ * field in every DSL adapter) and by the client runtime's `mapArray`, which
+ * used to skip depth entirely and always write plain `data-key` (#2753 Shape
+ * B). Living here, in the one package every one of those consumers already
+ * depends on, is what makes "compute it once" possible instead of aspirational.
+ */
+export declare function keyAttrName(loopDepth: number): string;
 /** Component placeholder in loop templates: `data-bf-ph="s5"` */
 export declare const BF_PLACEHOLDER = "data-bf-ph";
 /** Async boundary placeholder: `bf-async="a0"` */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/shared",
-  "version": "0.33.2",
+  "version": "0.33.3",
   "description": "Shared constants for BarefootJS compiler and runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -21,6 +21,7 @@ export {
   loopEndMarker,
   BF_KEY,
   BF_KEY_PREFIX,
+  keyAttrName,
   BF_PLACEHOLDER,
   BF_ASYNC,
   BF_ASYNC_RESOLVE,
@@ -43,6 +44,8 @@ export {
 } from './dom-prop.ts'
 export type { DOMPropKind, DOMPropClassification } from './dom-prop.ts'
 export { decodeEntities, escapeHtml } from './html-entities.ts'
+export { resolveJsxChildrenProp } from './jsx-children-prop.ts'
+export type { ChildrenSlotPropLike } from './jsx-children-prop.ts'
 
 export type {
   ProfilerEvent,

package/src/jsx-children-prop.ts

@@ -0,0 +1,61 @@
+/**
+ * BarefootJS — reserved `children` JSX-prop resolver
+ *
+ * Answers one question for every adapter: "which prop on this component
+ * call supplies the reserved `children` slot?" Before this module existed,
+ * two independently-maintained answers had drifted apart (issue #2773):
+ *
+ * - The seven DSL adapters (Blade/ERB/Jinja/Mojolicious/minijinja/Twig/
+ *   Xslate) each carried a byte-identical private copy of this function in
+ *   their own `lib/ir-scope.ts`, matching on the prop NAMED `children`.
+ * - The Go template adapter's `jsxChildrenPropNodes` answered a different
+ *   question: the FIRST prop of ANY name carrying a `jsx-children`
+ *   payload. For a component with an earlier JSX-element prop (e.g.
+ *   `header={<span/>}`) and no `children` prop at all, that silently
+ *   backfilled `.Children` with the `header` payload — and when a
+ *   `children` prop WAS also given, it lost `children`'s payload entirely
+ *   in favor of the earlier prop's.
+ *
+ * Hono, the reference adapter, resolves `children` by name — ordinary JSX
+ * semantics: `<Card header={<A/>} children={<B/>} />` binds `header` and
+ * `children` to two separate props, exactly as `React.createElement`
+ * would. The DSL adapters already agreed with Hono; this module makes
+ * their shared answer the ONLY implementation, so Go template (and any
+ * future adapter) calls it instead of growing its own copy that can
+ * re-diverge.
+ *
+ * Generic and structurally typed rather than importing `IRProp`/`IRNode`
+ * from `@barefootjs/jsx`: `@barefootjs/jsx` itself depends on
+ * `@barefootjs/shared`, so importing the other direction would be a
+ * dependency cycle. Callers pass their real IR prop array and get back a
+ * concretely-typed node array — no cast, no parallel type declaration to
+ * keep in sync with `@barefootjs/jsx`'s `AttrValue` union.
+ */
+
+/** Structural shape of an `AttrValue`-like prop value, generic over the node type a `jsx-children` payload carries. */
+interface JsxChildrenAttrValueLike<TNode> {
+  kind: string
+  children?: TNode[]
+}
+
+/** Structural shape of one IR prop, generic over the node type. */
+export interface ChildrenSlotPropLike<TNode> {
+  name: string
+  value: JsxChildrenAttrValueLike<TNode>
+}
+
+/**
+ * Find the prop literally named `children` and, if its value carries a
+ * `jsx-children` payload, return that payload's nodes. Returns `[]` when
+ * no `children` prop exists, or when one exists but is not a resolved
+ * JSX-children payload (e.g. an ordinary expression prop that merely
+ * happens to be named `children`).
+ */
+export function resolveJsxChildrenProp<TNode>(
+  props: ReadonlyArray<ChildrenSlotPropLike<TNode>>,
+): TNode[] {
+  const prop = props.find(p => p.name === 'children')
+  if (!prop) return []
+  if (prop.value.kind !== 'jsx-children') return []
+  return prop.value.children ?? []
+}

package/src/markers.ts

@@ -171,6 +171,24 @@ export const BF_KEY = 'data-key'
 /** Nested loop key attribute prefix: `data-key-1`, `data-key-2` */
 export const BF_KEY_PREFIX = 'data-key-'
 
+/**
+ * The row-key attribute NAME for a `.map()` nested `loopDepth` levels deep
+ * (0 = outermost): `data-key` at depth 0, `data-key-N` at depth N > 0.
+ *
+ * Single source of truth for a derivation that used to be re-implemented at
+ * every emission site — the CSR codegen path (`ir-to-client-js/utils.ts`,
+ * pre-existing re-export), IR-build time (`IRElement.keyAttr`,
+ * `jsx-to-ir.ts`), and — before that consolidation — independently again by
+ * each of the 9 SSR adapters (a mutable stack in Hono, a `currentLoopKeyDepth`
+ * field in every DSL adapter) and by the client runtime's `mapArray`, which
+ * used to skip depth entirely and always write plain `data-key` (#2753 Shape
+ * B). Living here, in the one package every one of those consumers already
+ * depends on, is what makes "compute it once" possible instead of aspirational.
+ */
+export function keyAttrName(loopDepth: number): string {
+  return loopDepth > 0 ? `${BF_KEY_PREFIX}${loopDepth}` : BF_KEY
+}
+
 /** Component placeholder in loop templates: `data-bf-ph="s5"` */
 export const BF_PLACEHOLDER = 'data-bf-ph'