@yahoo/uds-create-config 5.25.1 → 5.26.0

package/dist/renderer/componentEntry.js

@@ -1,6 +1,9 @@
+import { UDS_FORCE_STATES } from "../framework/component-states.js";
+import { forcedModifierAttributes } from "../framework/class-names.js";
 import { registerComputed } from "./computed.js";
 import { RendererErrorBoundary } from "./RendererErrorBoundary.js";
 import { specContent } from "./spec-content.js";
+import { useForcedModifierStamp } from "./use-forced-stamp.js";
 import React from "react";
 //#region src/renderer/componentEntry.tsx
 /**
@@ -33,11 +36,12 @@ function definedOnly(options) {
 * data, so it never imports this renderer: whoever assembles a registry makes the entry.
 */
 function makeComponentEntry(options) {
-	const { component: Comp, childless, name, computed } = {
+	const { component: Comp, childless, name, computed, states } = {
 		...options.component.__udsEntry,
 		...definedOnly(options)
 	};
 	const label = name ?? Comp.displayName ?? Comp.name ?? "component";
+	const componentPath = name?.startsWith("component:") ? name.slice(10) : label;
 	if (computed) registerComputed(computed);
 	return function ComponentEntry({ props: elementProps, children, slots }) {
 		let props = elementProps ?? {};
@@ -51,6 +55,18 @@ function makeComponentEntry(options) {
 			props = filled;
 		}
 		const { children: propChildren, ...rest } = props;
+		if (states?.some((state) => state in rest)) {
+			const forced = { ...rest["__udsForceStates"] ?? {} };
+			for (const state of states) {
+				if (!(state in rest)) continue;
+				forced[state] = rest[state];
+				delete rest[state];
+			}
+			rest[UDS_FORCE_STATES] = forced;
+		}
+		let forcedAttrs = {};
+		const pins = rest[UDS_FORCE_STATES];
+		if (pins && typeof pins === "object") forcedAttrs = forcedModifierAttributes(pins);
 		let rendered;
 		if (childless) rendered = React.createElement(Comp, rest);
 		else {
@@ -60,6 +76,10 @@ function makeComponentEntry(options) {
 			});
 			rendered = finalChildren !== void 0 && finalChildren !== null ? React.createElement(Comp, rest, finalChildren) : React.createElement(Comp, rest);
 		}
+		if (Object.keys(forcedAttrs).length > 0) rendered = React.createElement(ForcedHost, {
+			component: componentPath,
+			attributes: forcedAttrs
+		}, rendered);
 		return React.createElement(RendererErrorBoundary, {
 			name: label,
 			resetKey: elementProps
@@ -84,5 +104,14 @@ function entryRenderer(entry) {
 		});
 	};
 }
+/** A layout-neutral wrapper that marks the forced component's own elements under it. */
+function ForcedHost({ component, attributes, children }) {
+	const host = React.useRef(null);
+	useForcedModifierStamp(host, component, attributes);
+	return React.createElement("div", {
+		ref: host,
+		style: { display: "contents" }
+	}, children);
+}
 //#endregion
 export { entryRenderer, makeComponentEntry, slotFillValue };

package/dist/renderer/forced-stamp.d.ts

@@ -0,0 +1,26 @@
+//#region src/renderer/forced-stamp.d.ts
+/**
+ * Mark a forced component's own elements with its force attributes, inside `container`.
+ *
+ * The design sheet's force twin matches an element that carries the attribute itself, so a state is
+ * forced exactly where this puts it: the component's root, and its other elements tagged with its
+ * own `data-uds-component` — except the root of a component nested in it. That root is tagged with
+ * the parent's markers (the props it was given land over its own), but it is the nearest tagged
+ * ancestor of the nested component's own non-root parts, which is how it's told apart. A nested
+ * IconButton then keeps its own hover and focus ring, as the browser would. Returns the undo.
+ *
+ * Each attribute's value lists the components forced on the element, and this adds `component` to
+ * it: the twin matches only its own component's name (`forceStateSelector`), so a component
+ * whose root is another's instance — one element for both — doesn't light the inner one's state.
+ */
+declare function stampForcedModifiers({
+  container,
+  component,
+  attributes
+}: {
+  container: Element;
+  component: string;
+  attributes: Readonly<Record<string, string>>;
+}): () => void;
+//#endregion
+export { stampForcedModifiers };

package/dist/renderer/forced-stamp.js

@@ -0,0 +1,50 @@
+//#region src/renderer/forced-stamp.ts
+/**
+* Mark a forced component's own elements with its force attributes, inside `container`.
+*
+* The design sheet's force twin matches an element that carries the attribute itself, so a state is
+* forced exactly where this puts it: the component's root, and its other elements tagged with its
+* own `data-uds-component` — except the root of a component nested in it. That root is tagged with
+* the parent's markers (the props it was given land over its own), but it is the nearest tagged
+* ancestor of the nested component's own non-root parts, which is how it's told apart. A nested
+* IconButton then keeps its own hover and focus ring, as the browser would. Returns the undo.
+*
+* Each attribute's value lists the components forced on the element, and this adds `component` to
+* it: the twin matches only its own component's name (`forceStateSelector`), so a component
+* whose root is another's instance — one element for both — doesn't light the inner one's state.
+*/
+function stampForcedModifiers({ container, component, attributes }) {
+	const names = Object.keys(attributes);
+	if (names.length === 0) return () => {};
+	const tagged = [...container.querySelectorAll("[data-uds-component]")];
+	const nestedRoots = /* @__PURE__ */ new Set();
+	for (const element of tagged) {
+		if (element.getAttribute("data-uds-component") === component) continue;
+		if (element.getAttribute("data-uds-layer") === "root") continue;
+		const owner = element.parentElement?.closest("[data-uds-component]");
+		if (owner && owner.getAttribute("data-uds-component") === component) nestedRoots.add(owner);
+	}
+	const stamped = [];
+	for (const element of tagged) {
+		if (element.getAttribute("data-uds-component") !== component) continue;
+		if (!(element.getAttribute("data-uds-layer") === "root") && nestedRoots.has(element)) continue;
+		for (const name of names) {
+			const owners = ownersOf(element, name);
+			if (!owners.includes(component)) element.setAttribute(name, [...owners, component].join(" "));
+		}
+		stamped.push(element);
+	}
+	return () => {
+		for (const element of stamped) for (const name of names) {
+			const owners = ownersOf(element, name).filter((owner) => owner !== component);
+			if (owners.length > 0) element.setAttribute(name, owners.join(" "));
+			else element.removeAttribute(name);
+		}
+	};
+}
+/** The components a force attribute already names on an element. */
+function ownersOf(element, name) {
+	return (element.getAttribute(name) ?? "").split(/\s+/).filter(Boolean);
+}
+//#endregion
+export { stampForcedModifiers };

package/dist/renderer/index.d.ts

@@ -1,5 +1,6 @@
 import { ComponentEntry, ComponentEntryFacts, MakeComponentEntryOptions, entryRenderer, makeComponentEntry, slotFillValue } from "./componentEntry.js";
 import { computedFunctions, registerComputed, withComputedFunctions } from "./computed.js";
+import { stampForcedModifiers } from "./forced-stamp.js";
 import { GlyphEntriesResult, GlyphMembers, glyphRegistryEntries } from "./glyphEntries.js";
 import { FragmentRenderer } from "./primitives/FragmentRenderer.js";
 import { SlotRenderer } from "./primitives/SlotRenderer.js";
@@ -11,7 +12,8 @@ import { GlyphPropMap, wrapGlyphProps } from "./wrappers/glyph-props.js";
 import { VERBATIM_ATTRIBUTES, aliasHtmlTypes } from "./wrappers/html-aliases.js";
 import { RegistryDescriptor, wrapRegistry } from "./wrapRegistry.js";
 import { UdsRenderer, UdsRendererProps } from "./UdsRenderer.js";
+import { useForcedModifierStamp } from "./use-forced-stamp.js";
 import { wrapEventBridge } from "./wrappers/event-bridge.js";
 import { wrapNormalizeHex } from "./wrappers/hex-normalize.js";
 import { wrapInlineStyleProps } from "./wrappers/inline-styles.js";
-export { type ComponentEntry, type ComponentEntryFacts, FragmentRenderer, type Glyph, type GlyphEntriesResult, type GlyphLibrary, type GlyphMembers, type GlyphPropMap, type MakeComponentEntryOptions, REVEALED_LAYER_ATTR, type RegistryDescriptor, RendererErrorBoundary, type ResolvedGlyph, RuntimeComponentFailureContext, type RuntimeComponentFailureReporter, RuntimeComponentRebuildContext, type RuntimeComponentRebuildReporter, type RuntimeComponentScope, type RuntimeComponentStatus, type RuntimeComponentStore, RuntimeComponentStoreContext, SlotRenderer, UdsRenderer, type UdsRendererProps, VERBATIM_ATTRIBUTES, aliasHtmlTypes, computedFunctions, entryRenderer, glyphRegistryEntries, installRuntimeComponentStore, makeComponentEntry, registerComputed, resolveGlyph, runtimeComponent, slotFillValue, specContent, withComputedFunctions, wrapEventBridge, wrapGlyphProps, wrapInlineStyleProps, wrapNormalizeHex, wrapRegistry };
+export { type ComponentEntry, type ComponentEntryFacts, FragmentRenderer, type Glyph, type GlyphEntriesResult, type GlyphLibrary, type GlyphMembers, type GlyphPropMap, type MakeComponentEntryOptions, REVEALED_LAYER_ATTR, type RegistryDescriptor, RendererErrorBoundary, type ResolvedGlyph, RuntimeComponentFailureContext, type RuntimeComponentFailureReporter, RuntimeComponentRebuildContext, type RuntimeComponentRebuildReporter, type RuntimeComponentScope, type RuntimeComponentStatus, type RuntimeComponentStore, RuntimeComponentStoreContext, SlotRenderer, UdsRenderer, type UdsRendererProps, VERBATIM_ATTRIBUTES, aliasHtmlTypes, computedFunctions, entryRenderer, glyphRegistryEntries, installRuntimeComponentStore, makeComponentEntry, registerComputed, resolveGlyph, runtimeComponent, slotFillValue, specContent, stampForcedModifiers, useForcedModifierStamp, withComputedFunctions, wrapEventBridge, wrapGlyphProps, wrapInlineStyleProps, wrapNormalizeHex, wrapRegistry };

package/dist/renderer/index.js

@@ -1,6 +1,8 @@
 import { computedFunctions, registerComputed, withComputedFunctions } from "./computed.js";
 import { RendererErrorBoundary } from "./RendererErrorBoundary.js";
 import { REVEALED_LAYER_ATTR, specContent } from "./spec-content.js";
+import { stampForcedModifiers } from "./forced-stamp.js";
+import { useForcedModifierStamp } from "./use-forced-stamp.js";
 import { entryRenderer, makeComponentEntry, slotFillValue } from "./componentEntry.js";
 import { resolveGlyph } from "./resolveGlyph.js";
 import { glyphRegistryEntries } from "./glyphEntries.js";
@@ -14,4 +16,4 @@ import { VERBATIM_ATTRIBUTES, aliasHtmlTypes } from "./wrappers/html-aliases.js"
 import { wrapInlineStyleProps } from "./wrappers/inline-styles.js";
 import { wrapRegistry } from "./wrapRegistry.js";
 import { UdsRenderer } from "./UdsRenderer.js";
-export { FragmentRenderer, REVEALED_LAYER_ATTR, RendererErrorBoundary, RuntimeComponentFailureContext, RuntimeComponentRebuildContext, RuntimeComponentStoreContext, SlotRenderer, UdsRenderer, VERBATIM_ATTRIBUTES, aliasHtmlTypes, computedFunctions, entryRenderer, glyphRegistryEntries, installRuntimeComponentStore, makeComponentEntry, registerComputed, resolveGlyph, runtimeComponent, slotFillValue, specContent, withComputedFunctions, wrapEventBridge, wrapGlyphProps, wrapInlineStyleProps, wrapNormalizeHex, wrapRegistry };
+export { FragmentRenderer, REVEALED_LAYER_ATTR, RendererErrorBoundary, RuntimeComponentFailureContext, RuntimeComponentRebuildContext, RuntimeComponentStoreContext, SlotRenderer, UdsRenderer, VERBATIM_ATTRIBUTES, aliasHtmlTypes, computedFunctions, entryRenderer, glyphRegistryEntries, installRuntimeComponentStore, makeComponentEntry, registerComputed, resolveGlyph, runtimeComponent, slotFillValue, specContent, stampForcedModifiers, useForcedModifierStamp, withComputedFunctions, wrapEventBridge, wrapGlyphProps, wrapInlineStyleProps, wrapNormalizeHex, wrapRegistry };

package/dist/renderer/use-forced-stamp.d.ts

@@ -0,0 +1,11 @@
+import { RefObject } from "react";
+
+//#region src/renderer/use-forced-stamp.d.ts
+/**
+ * Keep a forced component's own elements under `ref` marked with `attributes` (see
+ * {@link stampForcedModifiers}) as its DOM renders and re-renders: marked after every commit, and
+ * again when the subtree changes underneath (a lazy layer mounting, a module swapping in).
+ */
+declare function useForcedModifierStamp(ref: RefObject<Element | null>, component: string, attributes: Readonly<Record<string, string>>): void;
+//#endregion
+export { useForcedModifierStamp };

package/dist/renderer/use-forced-stamp.js

@@ -0,0 +1,50 @@
+import { stampForcedModifiers } from "./forced-stamp.js";
+import { useLayoutEffect, useRef } from "react";
+//#region src/renderer/use-forced-stamp.ts
+/**
+* Keep a forced component's own elements under `ref` marked with `attributes` (see
+* {@link stampForcedModifiers}) as its DOM renders and re-renders: marked after every commit, and
+* again when the subtree changes underneath (a lazy layer mounting, a module swapping in).
+*/
+function useForcedModifierStamp(ref, component, attributes) {
+	const key = Object.keys(attributes).sort().join("|");
+	const latest = useRef(attributes);
+	latest.current = attributes;
+	useLayoutEffect(() => {
+		const container = ref.current;
+		if (!container || key === "") return;
+		const attributes = latest.current;
+		let undo = stampForcedModifiers({
+			container,
+			component,
+			attributes
+		});
+		const observer = new MutationObserver(() => {
+			observer.disconnect();
+			undo();
+			undo = stampForcedModifiers({
+				container,
+				component,
+				attributes
+			});
+			observer.observe(container, {
+				childList: true,
+				subtree: true
+			});
+		});
+		observer.observe(container, {
+			childList: true,
+			subtree: true
+		});
+		return () => {
+			observer.disconnect();
+			undo();
+		};
+	}, [
+		ref,
+		component,
+		key
+	]);
+}
+//#endregion
+export { useForcedModifierStamp };

package/dist/spec/specToJsx.d.ts

@@ -32,6 +32,12 @@ interface SpecToJsxOptions {
    * package that exports it.
    */
   glyphMembers?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Component type → the states it declares. A design-time instance may pin one (a canvas mock of a
+   * filled field); a state is never a prop, so code leaves it out rather than writing
+   * `<Input filled />`, which would force the look in production.
+   */
+  states?: Readonly<Record<string, readonly string[]>>;
 }
 interface SpecToJsxResult {
   /** Generated JSX source code */

package/dist/spec/specToJsx.js

@@ -1,3 +1,5 @@
+import { UDS_FORCE_STATES } from "../framework/component-states.js";
+import "../framework/class-names.js";
 import { glyphJsxForm, glyphMemberOf, jsxIdentifier, parseGlyphType } from "./glyph-jsx.js";
 import { serializeProps } from "@json-render/codegen";
 //#region src/spec/specToJsx.ts
@@ -108,6 +110,8 @@ function renderElement(key, spec, depth, ctx, ancestors) {
 	if (ancestors.has(key)) return `${indent}{/* cyclic reference to "${key}" omitted */}`;
 	const withSelf = new Set(ancestors).add(key);
 	const { children: _children, ...propsWithoutSlots } = element.props ?? {};
+	delete propsWithoutSlots[UDS_FORCE_STATES];
+	for (const state of ctx.states?.[element.type] ?? []) delete propsWithoutSlots[state];
 	const slotKeys = collectSlotKeys(element.slots);
 	const slotAttrs = [];
 	for (const [propName, fills] of Object.entries(element.slots ?? {})) if (fills.length === 1) {
@@ -207,6 +211,7 @@ function specToJsx(spec, options) {
 		glyphModules: options?.glyphModules,
 		glyphProps: options?.glyphProps,
 		glyphMembers: options?.glyphMembers,
+		states: options?.states,
 		members: /* @__PURE__ */ new Map()
 	};
 	const jsxTree = renderElement(spec.root, spec, 0, ctx, /* @__PURE__ */ new Set());