@jfdevelops/react-layout 0.24.2 → 0.25.0

package/dist/create-config/lazy-resource-layout.mjs

@@ -0,0 +1,111 @@
+import { LayoutConfigurationError } from "../errors/layout-configuration-error.mjs";
+import { ResourceModuleLoadError } from "../errors/resource-state-error.mjs";
+import { definedResourceLayoutComponentSymbol } from "./render-state.mjs";
+import { Component, Suspense, lazy, useReducer, useRef } from "react";
+import { componentPropDefinitionsSymbol } from "@jfdevelops/react-layout-validator";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/create-config/lazy-resource-layout.tsx
+var LazyResourceErrorBoundary = class extends Component {
+	state = {};
+	static getDerivedStateFromError(error) {
+		return { error };
+	}
+	retry = () => {
+		this.props.onRetry();
+		this.setState({ error: void 0 });
+	};
+	render() {
+		if (this.state.error !== void 0) {
+			const { ErrorComponent } = this.props;
+			if (!ErrorComponent) throw this.state.error;
+			return /* @__PURE__ */ jsx(ErrorComponent, {
+				error: this.state.error,
+				retry: this.retry
+			});
+		}
+		return this.props.children;
+	}
+};
+function findDefinedLayoutComponent(module) {
+	const components = Object.values(module).filter((value) => typeof value === "function" && definedResourceLayoutComponentSymbol in value);
+	if (components.length !== 1) throw new LayoutConfigurationError(`A lazy resource module must export exactly one created resource layout component; received ${components.length}`);
+	return components[0];
+}
+/**
+* Creates a cached lazy proxy for a resource component and all of its compound
+* state components. This is normally called through
+* `defineResourceLayout.lazy(...)`, which supplies shared defaults.
+*/
+function createLazyResourceLayout(options, defaults) {
+	const runtimeOptions = options;
+	let loadedComponentPromise;
+	const stateComponents = /* @__PURE__ */ new Map();
+	const resolvedStates = {
+		...defaults,
+		...runtimeOptions.states
+	};
+	function loadComponent() {
+		loadedComponentPromise ??= runtimeOptions.load().then(findDefinedLayoutComponent).catch((error) => {
+			throw new ResourceModuleLoadError(runtimeOptions.resource, error);
+		});
+		return loadedComponentPromise;
+	}
+	function resetLoad() {
+		loadedComponentPromise = void 0;
+		stateComponents.clear();
+	}
+	function createMemberComponent(member) {
+		function createLazyComponent() {
+			return lazy(async () => {
+				const component = await loadComponent();
+				const selected = member === void 0 ? component : component[member];
+				if (typeof selected !== "function") throw new LayoutConfigurationError(`Lazy resource "${runtimeOptions.resource}" does not define state "${String(member)}"`);
+				return { default: selected };
+			});
+		}
+		function LazyMember(props) {
+			const [, rerender] = useReducer((version) => version + 1, 0);
+			const LazyComponent = useRef(createLazyComponent());
+			const LoadingComponent = resolvedStates.Loading;
+			const CurrentLazyComponent = LazyComponent.current;
+			function retry() {
+				resetLoad();
+				LazyComponent.current = createLazyComponent();
+				rerender();
+			}
+			return /* @__PURE__ */ jsx(LazyResourceErrorBoundary, {
+				ErrorComponent: resolvedStates.Error,
+				onRetry: retry,
+				children: /* @__PURE__ */ jsx(Suspense, {
+					fallback: LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null,
+					children: /* @__PURE__ */ jsx(CurrentLazyComponent, { ...props })
+				})
+			});
+		}
+		const resourceName = runtimeOptions.resource;
+		LazyMember.displayName = member === void 0 ? `LazyResource(${resourceName})` : `LazyResource(${resourceName}).${String(member)}`;
+		return LazyMember;
+	}
+	const Component = createMemberComponent();
+	const unsupportedStatics = new Set([
+		"makeComposable",
+		"props",
+		"resource",
+		componentPropDefinitionsSymbol,
+		definedResourceLayoutComponentSymbol
+	]);
+	return new Proxy(Component, { get(target, property, receiver) {
+		if (Reflect.has(target, property)) return Reflect.get(target, property, receiver);
+		if (typeof property !== "string" || unsupportedStatics.has(property)) return;
+		const existing = stateComponents.get(property);
+		if (existing) return existing;
+		const stateComponent = createMemberComponent(property);
+		stateComponents.set(property, stateComponent);
+		return stateComponent;
+	} });
+}
+
+//#endregion
+export { createLazyResourceLayout };
+//# sourceMappingURL=lazy-resource-layout.mjs.map

package/dist/create-config/lazy-resource-layout.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-resource-layout.mjs","names":[],"sources":["../../src/create-config/lazy-resource-layout.tsx"],"sourcesContent":["import {\n  Component,\n  type ComponentProps,\n  type ComponentType,\n  type JSX,\n  lazy,\n  Suspense,\n  useReducer,\n  useRef,\n} from 'react';\nimport {\n  LayoutConfigurationError,\n  ResourceModuleLoadError,\n} from '../errors';\nimport { componentPropDefinitionsSymbol } from '@jfdevelops/react-layout-validator';\nimport type { ResourcePath, ResourceDefinition } from '../resource';\nimport { definedResourceLayoutComponentSymbol } from './render-state';\n\ntype DefinedLayoutComponent = ComponentType<any> & {\n  readonly [definedResourceLayoutComponentSymbol]: true;\n};\n\ntype DefinedLayoutFromModule<Module> = Extract<\n  Module[keyof Module],\n  DefinedLayoutComponent\n>;\n\ntype LazyUnsupportedStatic =\n  | 'makeComposable'\n  | 'props'\n  | 'resource'\n  | typeof componentPropDefinitionsSymbol\n  | typeof definedResourceLayoutComponentSymbol;\n\n/**\n * Public surface available before a lazy module resolves. Component metadata\n * and composition factories are intentionally omitted because they cannot be\n * read synchronously without loading the module.\n */\nexport type LazyResourceLayoutComponent<Module> = ComponentType<\n  ComponentProps<DefinedLayoutFromModule<Module>>\n> &\n  Pick<\n    DefinedLayoutFromModule<Module>,\n    Exclude<keyof DefinedLayoutFromModule<Module>, LazyUnsupportedStatic>\n  >;\n\n/** Component rendered while a resource module or one of its states is loading. */\nexport type LazyResourceLoadingComponent = ComponentType;\n/**\n * Component rendered when a resource module cannot be loaded. Calling\n * `retry` discards React's rejected lazy cache entry and imports it again.\n */\nexport type LazyResourceErrorComponent = ComponentType<{\n  error: unknown;\n  retry: () => void;\n}>;\n\n/** Loading and module-error UI used around a lazy resource component. */\nexport type LazyResourceStates = {\n  Error?: LazyResourceErrorComponent;\n  Loading?: LazyResourceLoadingComponent;\n};\n\n/**\n * Configuration for a lazy resource component. `resource` is checked against\n * the bound resource paths, including dot-delimited subresources, and `load`\n * must resolve to a module with exactly one created resource component.\n */\nexport type LazyResourceLayoutOptions<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Module extends Record<string, unknown>,\n> = {\n  load: () => Promise<Module>;\n  resource: ResourcePath<Resources>;\n  states?: LazyResourceStates;\n};\n\ntype BoundaryProps = {\n  children: JSX.Element;\n  ErrorComponent?: LazyResourceErrorComponent;\n  onRetry: () => void;\n};\n\ntype BoundaryState = {\n  error?: unknown;\n};\n\nclass LazyResourceErrorBoundary extends Component<\n  BoundaryProps,\n  BoundaryState\n> {\n  state: BoundaryState = {};\n\n  static getDerivedStateFromError(error: unknown): BoundaryState {\n    return { error };\n  }\n\n  retry = () => {\n    this.props.onRetry();\n    this.setState({ error: undefined });\n  };\n\n  render() {\n    if (this.state.error !== undefined) {\n      const { ErrorComponent } = this.props;\n\n      if (!ErrorComponent) {\n        throw this.state.error;\n      }\n\n      return <ErrorComponent error={this.state.error} retry={this.retry} />;\n    }\n\n    return this.props.children;\n  }\n}\n\nfunction findDefinedLayoutComponent(module: Record<string, unknown>) {\n  const components = Object.values(module).filter(\n    (value): value is DefinedLayoutComponent =>\n      typeof value === 'function' &&\n      definedResourceLayoutComponentSymbol in value,\n  );\n\n  if (components.length !== 1) {\n    throw new LayoutConfigurationError(\n      `A lazy resource module must export exactly one created resource layout component; received ${components.length}`,\n    );\n  }\n\n  return components[0];\n}\n\n/**\n * Creates a cached lazy proxy for a resource component and all of its compound\n * state components. This is normally called through\n * `defineResourceLayout.lazy(...)`, which supplies shared defaults.\n */\nexport function createLazyResourceLayout<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Module extends Record<string, unknown>,\n>(\n  options: LazyResourceLayoutOptions<Resources, Module>,\n  defaults: LazyResourceStates,\n): LazyResourceLayoutComponent<Module> {\n  const runtimeOptions = options as {\n    load: () => Promise<Record<string, unknown>>;\n    resource: string;\n    states?: LazyResourceStates;\n  };\n  let loadedComponentPromise: Promise<DefinedLayoutComponent> | undefined;\n  const stateComponents = new Map<PropertyKey, ComponentType<any>>();\n  const resolvedStates = { ...defaults, ...runtimeOptions.states };\n\n  function loadComponent() {\n    loadedComponentPromise ??= runtimeOptions\n      .load()\n      .then(findDefinedLayoutComponent)\n      .catch((error: unknown) => {\n        throw new ResourceModuleLoadError(runtimeOptions.resource, error);\n      });\n\n    return loadedComponentPromise;\n  }\n\n  function resetLoad() {\n    loadedComponentPromise = undefined;\n    stateComponents.clear();\n  }\n\n  function createMemberComponent(member?: PropertyKey) {\n    function createLazyComponent() {\n      return lazy(async () => {\n        const component = await loadComponent();\n        const selected =\n          member === undefined\n            ? component\n            : (component as unknown as Record<PropertyKey, unknown>)[member];\n\n        if (typeof selected !== 'function') {\n          throw new LayoutConfigurationError(\n            `Lazy resource \"${runtimeOptions.resource}\" does not define state \"${String(member)}\"`,\n          );\n        }\n\n        return { default: selected as ComponentType<any> };\n      });\n    }\n\n    function LazyMember(props: Record<string, unknown>) {\n      const [, rerender] = useReducer((version) => version + 1, 0);\n      const LazyComponent = useRef(createLazyComponent());\n      const LoadingComponent = resolvedStates.Loading;\n      const CurrentLazyComponent = LazyComponent.current;\n\n      function retry() {\n        resetLoad();\n        LazyComponent.current = createLazyComponent();\n        rerender();\n      }\n\n      return (\n        <LazyResourceErrorBoundary\n          ErrorComponent={resolvedStates.Error}\n          onRetry={retry}\n        >\n          <Suspense\n            fallback={LoadingComponent ? <LoadingComponent /> : null}\n          >\n            <CurrentLazyComponent {...props} />\n          </Suspense>\n        </LazyResourceErrorBoundary>\n      );\n    }\n\n    const resourceName = runtimeOptions.resource;\n    LazyMember.displayName =\n      member === undefined\n        ? `LazyResource(${resourceName})`\n        : `LazyResource(${resourceName}).${String(member)}`;\n\n    return LazyMember;\n  }\n\n  const Component = createMemberComponent();\n  const unsupportedStatics = new Set<PropertyKey>([\n    'makeComposable',\n    'props',\n    'resource',\n    componentPropDefinitionsSymbol,\n    definedResourceLayoutComponentSymbol,\n  ]);\n\n  return new Proxy(Component, {\n    get(target, property, receiver) {\n      if (Reflect.has(target, property)) {\n        return Reflect.get(target, property, receiver);\n      }\n\n      if (typeof property !== 'string' || unsupportedStatics.has(property)) {\n        return undefined;\n      }\n\n      const existing = stateComponents.get(property);\n\n      if (existing) {\n        return existing;\n      }\n\n      const stateComponent = createMemberComponent(property);\n      stateComponents.set(property, stateComponent);\n\n      return stateComponent;\n    },\n  }) as unknown as LazyResourceLayoutComponent<Module>;\n}\n"],"mappings":"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"}

package/dist/create-config/render-state.cjs

@@ -0,0 +1,75 @@
+
+//#region src/create-config/render-state.ts
+const deferredRenderStateSymbol = Symbol("deferredRenderState");
+const lazyRenderStateSymbol = Symbol("lazyRenderState");
+const definedRenderStateSymbol = Symbol.for("@jfdevelops/react-layout/render-state");
+const definedResourceLayoutComponentSymbol = Symbol.for("@jfdevelops/react-layout/resource-layout-component");
+function normalizeDefinition(input) {
+	return typeof input === "function" ? {
+		render: input,
+		state: "default"
+	} : input;
+}
+function toFragment(definition) {
+	const fragment = { [definition.state ?? "default"]: definition };
+	Object.defineProperty(fragment, definedRenderStateSymbol, {
+		enumerable: false,
+		value: definition
+	});
+	return fragment;
+}
+/**
+* Creates a state factory whose `props.include` keys are constrained by the
+* supplied resources and options.
+*/
+function createRenderStateBuilder(_arguments) {
+	function createRenderState(input) {
+		return toFragment(normalizeDefinition(input));
+	}
+	createRenderState.defer = (input) => {
+		const definition = normalizeDefinition(input);
+		return { [definition.state ?? "default"]: { [deferredRenderStateSymbol]: definition } };
+	};
+	createRenderState.lazy = (load) => ({ [lazyRenderStateSymbol]: load });
+	return createRenderState;
+}
+/** Type guard for states created with `createRenderState.defer(...)`. */
+function isDeferredRenderState(value) {
+	return typeof value === "object" && value !== null && deferredRenderStateSymbol in value;
+}
+/** Type guard for states created with `createRenderState.lazy(...)`. */
+function isLazyRenderState(value) {
+	return typeof value === "object" && value !== null && lazyRenderStateSymbol in value;
+}
+/**
+* Selects the single state definition exported by a lazy module. Throws when
+* the module exports none or more than one, avoiding ambiguous selection.
+*/
+function findDefinedRenderState(module) {
+	const definitions = Object.values(module).filter((value) => typeof value === "object" && value !== null && definedRenderStateSymbol in value);
+	if (definitions.length !== 1) throw new Error(`A lazy render-state module must export exactly one defined render state; received ${definitions.length}.`);
+	return definitions[0][definedRenderStateSymbol];
+}
+/**
+* Creates the reusable `composables` and `createRenderState` helpers without
+* introducing an identity wrapper around the layout object itself.
+*/
+function createLayoutBuildingBlocks(arguments_) {
+	function composables(definition) {
+		return definition;
+	}
+	return {
+		composables,
+		createRenderState: createRenderStateBuilder(arguments_)
+	};
+}
+
+//#endregion
+exports.createLayoutBuildingBlocks = createLayoutBuildingBlocks;
+exports.deferredRenderStateSymbol = deferredRenderStateSymbol;
+exports.definedResourceLayoutComponentSymbol = definedResourceLayoutComponentSymbol;
+exports.findDefinedRenderState = findDefinedRenderState;
+exports.isDeferredRenderState = isDeferredRenderState;
+exports.isLazyRenderState = isLazyRenderState;
+exports.lazyRenderStateSymbol = lazyRenderStateSymbol;
+//# sourceMappingURL=render-state.cjs.map

package/dist/create-config/render-state.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-state.cjs","names":[],"sources":["../../src/create-config/render-state.ts"],"sourcesContent":["import type { JSX } from 'react';\nimport type {\n  ComposableComponents,\n  CreateLayoutComposable,\n} from '@jfdevelops/react-layout-composables';\nimport type { InPropsObject } from '../props';\nimport type {\n  IncludedProps,\n  InPropsDefinition,\n  LayoutRenderProps,\n  MergedLayoutInProps,\n} from '../props';\nimport type { LayoutResourceKey, ResourceDefinition } from '../resource';\n\nexport const deferredRenderStateSymbol: unique symbol = Symbol(\n  'deferredRenderState',\n) as never;\nexport const lazyRenderStateSymbol: unique symbol = Symbol(\n  'lazyRenderState',\n) as never;\nexport const definedRenderStateSymbol: unique symbol = Symbol.for(\n  '@jfdevelops/react-layout/render-state',\n) as never;\nexport const definedResourceLayoutComponentSymbol: unique symbol = Symbol.for(\n  '@jfdevelops/react-layout/resource-layout-component',\n) as never;\n\n/** Runtime-compatible render-state shape used when inspecting lazy modules. */\nexport type AnyRenderStateDefinition = {\n  composables?: (create: CreateLayoutComposable<any>) => ComposableComponents;\n  props?: {\n    include?: Record<string, unknown>;\n    custom?: InPropsObject;\n  };\n  render: (props: any, context: any) => JSX.Element;\n  state?: string;\n};\n\n/** An inline state whose first render is scheduled through `React.lazy`. */\nexport type DeferredRenderState<Definition extends AnyRenderStateDefinition> = {\n  readonly [deferredRenderStateSymbol]: Definition;\n};\n\n/** A state definition supplied by a separately imported module. */\nexport type LazyRenderState<Definition extends AnyRenderStateDefinition> = {\n  readonly [lazyRenderStateSymbol]: () => Promise<Record<string, unknown>>;\n  readonly definition?: Definition;\n};\n\n/** Callback shorthand for a render state with no local configuration. */\nexport type RenderStateCallback = (props: any, context: any) => JSX.Element;\n\n/**\n * Defines state-local composable components with a `create` helper narrowed to\n * the resources bound to the surrounding builder.\n */\nexport type RenderStateComposablesDefinition<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Composables extends ComposableComponents,\n> = (\n  create: CreateLayoutComposable<LayoutResourceKey<Resources>>,\n) => Composables;\n\n/**\n * Defines reusable layout-level composables while preserving their inferred\n * names, props, and bound resource union.\n */\nexport type LayoutComposablesDefinition<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Composables extends ComposableComponents,\n> = RenderStateComposablesDefinition<Resources, Composables>;\n\ntype BuilderRenderComposables<Composables extends ComposableComponents> = [\n  keyof Composables,\n] extends [never]\n  ? undefined\n  : Composables;\n\n/** Values available as the second argument of a created state's `render`. */\nexport type RenderStateContext<\n  Composables extends ComposableComponents,\n> = {\n  composables: BuilderRenderComposables<Composables>;\n  retry?: () => void;\n};\n\n/**\n * Resolves one state's custom props and explicitly included option/composable\n * props to the values received by its render callback.\n */\nexport type RenderStateProps<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n  Composables extends ComposableComponents,\n  IncludeProps extends IncludedProps<\n    MergedLayoutInProps<Resources, Options, Composables>\n  >,\n  CustomProps extends InPropsObject,\n> = LayoutRenderProps<\n  Resources,\n  Options,\n  Composables,\n  IncludeProps,\n  CustomProps\n>;\n\ntype TypedRenderStateDefinition<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n  State extends string,\n  CustomProps extends InPropsObject,\n  Composables extends ComposableComponents,\n  IncludeProps extends IncludedProps<\n    MergedLayoutInProps<Resources, Options, Composables>\n  >,\n> = {\n  composables?: RenderStateComposablesDefinition<Resources, Composables>;\n  props?: {\n    include?: IncludeProps;\n    custom?: CustomProps;\n  };\n  render: (\n    props: RenderStateProps<\n      Resources,\n      Options,\n      Composables,\n      IncludeProps,\n      CustomProps\n    >,\n    context: RenderStateContext<Composables>,\n  ) => JSX.Element;\n  state: State;\n};\n\ntype NormalizeRenderStateDefinition<Input> =\n  Input extends DeferredRenderState<infer Definition>\n    ? Definition\n    : Input extends RenderStateCallback\n      ? { render: Input; state: 'default' }\n      : Input extends AnyRenderStateDefinition\n        ? Input\n        : never;\n\ntype StateName<Definition> = Definition extends DeferredRenderState<\n  infer DeferredDefinition\n>\n  ? StateName<DeferredDefinition>\n  : Definition extends { state?: infer State extends string }\n    ? State\n    : 'default';\n\n/**\n * A spreadable state entry keyed by its literal state name. Spreading this into\n * `layout.render` is what creates compound members such as `Users.Loading`.\n */\nexport type RenderStateFragment<Definition> = {\n  [State in StateName<NormalizeRenderStateDefinition<Definition>>]: Definition;\n} & {\n  readonly [definedRenderStateSymbol]: NormalizeRenderStateDefinition<Definition>;\n};\n\ntype DefinedRenderStateFromModule<Module> = Extract<\n  Module[keyof Module],\n  { readonly [definedRenderStateSymbol]: AnyRenderStateDefinition }\n>[typeof definedRenderStateSymbol];\n\n/**\n * Creates independently typed render-state fragments.\n *\n * - Calling it directly creates an eager state.\n * - `.defer(...)` schedules an inline definition through `React.lazy`, but\n *   does not create a separate JavaScript chunk.\n * - `.lazy(() => import(...))` imports a complete named state definition as a\n *   separate chunk.\n */\nexport type CreateRenderState<\n  Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources> = {},\n> = {\n  <\n    const State extends string = 'default',\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      Composables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      Composables,\n      IncludeProps\n    >\n  >;\n  <\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        Composables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      'default',\n      CustomProps,\n      Composables,\n      IncludeProps\n    >\n  >;\n  <const Render extends RenderStateCallback>(\n    render: Render,\n  ): RenderStateFragment<Render>;\n  defer<\n    const State extends string = 'default',\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      Composables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        State,\n        CustomProps,\n        Composables,\n        IncludeProps\n      >\n    >\n  >;\n  defer<\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        Composables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        Composables,\n        IncludeProps\n      >\n    >\n  >;\n  defer<const Render extends RenderStateCallback>(\n    render: Render,\n  ): RenderStateFragment<DeferredRenderState<{ render: Render; state: 'default' }>>;\n  lazy<Module extends Record<string, unknown>>(\n    load: () => Promise<Module>,\n  ): LazyRenderState<DefinedRenderStateFromModule<Module>>;\n};\n\nfunction normalizeDefinition(\n  input: AnyRenderStateDefinition | RenderStateCallback,\n): AnyRenderStateDefinition {\n  return typeof input === 'function'\n    ? { render: input, state: 'default' }\n    : input;\n}\n\nfunction toFragment<Definition extends AnyRenderStateDefinition>(\n  definition: Definition,\n) {\n  const fragment = {\n    [definition.state ?? 'default']: definition,\n  } as RenderStateFragment<Definition>;\n\n  Object.defineProperty(fragment, definedRenderStateSymbol, {\n    enumerable: false,\n    value: definition,\n  });\n\n  return fragment;\n}\n\n/** Inputs used internally to bind resource and option types to a state builder. */\nexport type CreateRenderStateBuilderArguments<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = {\n  options: Options;\n  resources: Resources;\n};\n\n/** The state factory produced for a particular resource and option definition. */\nexport type CreateRenderStateBuilderResult<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = CreateRenderState<Resources, Options>;\n\n/**\n * Creates a state factory whose `props.include` keys are constrained by the\n * supplied resources and options.\n */\nexport function createRenderStateBuilder<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n>(\n  _arguments: CreateRenderStateBuilderArguments<Resources, Options>,\n): CreateRenderStateBuilderResult<Resources, Options> {\n  function createRenderState(\n    input: AnyRenderStateDefinition | RenderStateCallback,\n  ) {\n    return toFragment(normalizeDefinition(input));\n  }\n\n  createRenderState.defer = (\n    input: AnyRenderStateDefinition | RenderStateCallback,\n  ) => {\n    const definition = normalizeDefinition(input);\n\n    return {\n      [definition.state ?? 'default']: {\n        [deferredRenderStateSymbol]: definition,\n      },\n    };\n  };\n  createRenderState.lazy = (\n    load: () => Promise<Record<string, unknown>>,\n  ) => ({\n    [lazyRenderStateSymbol]: load,\n  });\n\n  return createRenderState as CreateRenderStateBuilderResult<Resources, Options>;\n}\n\n/** Type guard for states created with `createRenderState.defer(...)`. */\nexport function isDeferredRenderState(\n  value: unknown,\n): value is DeferredRenderState<AnyRenderStateDefinition> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    deferredRenderStateSymbol in value\n  );\n}\n\n/** Type guard for states created with `createRenderState.lazy(...)`. */\nexport function isLazyRenderState(\n  value: unknown,\n): value is LazyRenderState<AnyRenderStateDefinition> {\n  return (\n    typeof value === 'object' && value !== null && lazyRenderStateSymbol in value\n  );\n}\n\n/**\n * Selects the single state definition exported by a lazy module. Throws when\n * the module exports none or more than one, avoiding ambiguous selection.\n */\nexport function findDefinedRenderState(\n  module: Record<string, unknown>,\n): AnyRenderStateDefinition {\n  const definitions = Object.values(module).filter(\n    (value) =>\n      typeof value === 'object' && value !== null && definedRenderStateSymbol in value,\n  ) as Array<Record<typeof definedRenderStateSymbol, AnyRenderStateDefinition>>;\n\n  if (definitions.length !== 1) {\n    throw new Error(\n      `A lazy render-state module must export exactly one defined render state; received ${definitions.length}.`,\n    );\n  }\n\n  return definitions[0][definedRenderStateSymbol];\n}\n\n/** Identity helper that contextually types a reusable composables callback. */\nexport type DefineLayoutComposables<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n> = <const Composables extends ComposableComponents>(\n  definition: LayoutComposablesDefinition<Resources, Composables>,\n) => LayoutComposablesDefinition<Resources, Composables>;\n\n/** Public cross-file building blocks returned by a defined layout builder. */\nexport type CreateLayoutBuildingBlocks<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = {\n  composables: DefineLayoutComposables<Resources>;\n  createRenderState: CreateRenderState<Resources, Options>;\n};\n\n/** Resource and option bindings used to create layout building blocks. */\nexport type CreateLayoutBuildingBlocksArguments<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = CreateRenderStateBuilderArguments<Resources, Options>;\n\n/** Layout helpers produced for the supplied resource and option bindings. */\nexport type CreateLayoutBuildingBlocksResult<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = CreateLayoutBuildingBlocks<Resources, Options>;\n\n/**\n * Creates the reusable `composables` and `createRenderState` helpers without\n * introducing an identity wrapper around the layout object itself.\n */\nexport function createLayoutBuildingBlocks<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n>(\n  arguments_: CreateLayoutBuildingBlocksArguments<Resources, Options>,\n): CreateLayoutBuildingBlocksResult<Resources, Options> {\n  function composables<const Composables extends ComposableComponents>(\n    definition: LayoutComposablesDefinition<Resources, Composables>,\n  ): LayoutComposablesDefinition<Resources, Composables> {\n    return definition;\n  }\n\n  return {\n    composables,\n    createRenderState: createRenderStateBuilder(arguments_),\n  };\n}\n\n/** Preserves a bound resource tuple for consumers that need to re-export it. */\nexport type BoundResources<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n> = Resources;\n"],"mappings":";;AAcA,MAAa,4BAA2C,OACtD,qBACF;AACA,MAAa,wBAAuC,OAClD,iBACF;AACA,MAAa,2BAA0C,OAAO,IAC5D,uCACF;AACA,MAAa,uCAAsD,OAAO,IACxE,oDACF;AAqRA,SAAS,oBACP,OAC0B;CAC1B,OAAO,OAAO,UAAU,aACpB;EAAE,QAAQ;EAAO,OAAO;CAAU,IAClC;AACN;AAEA,SAAS,WACP,YACA;CACA,MAAM,WAAW,GACd,WAAW,SAAS,YAAY,WACnC;CAEA,OAAO,eAAe,UAAU,0BAA0B;EACxD,YAAY;EACZ,OAAO;CACT,CAAC;CAED,OAAO;AACT;;;;;AAqBA,SAAgB,yBAId,YACoD;CACpD,SAAS,kBACP,OACA;EACA,OAAO,WAAW,oBAAoB,KAAK,CAAC;CAC9C;CAEA,kBAAkB,SAChB,UACG;EACH,MAAM,aAAa,oBAAoB,KAAK;EAE5C,OAAO,GACJ,WAAW,SAAS,YAAY,GAC9B,4BAA4B,WAC/B,EACF;CACF;CACA,kBAAkB,QAChB,UACI,GACH,wBAAwB,KAC3B;CAEA,OAAO;AACT;;AAGA,SAAgB,sBACd,OACwD;CACxD,OACE,OAAO,UAAU,YACjB,UAAU,QACV,6BAA6B;AAEjC;;AAGA,SAAgB,kBACd,OACoD;CACpD,OACE,OAAO,UAAU,YAAY,UAAU,QAAQ,yBAAyB;AAE5E;;;;;AAMA,SAAgB,uBACd,QAC0B;CAC1B,MAAM,cAAc,OAAO,OAAO,MAAM,EAAE,QACvC,UACC,OAAO,UAAU,YAAY,UAAU,QAAQ,4BAA4B,KAC/E;CAEA,IAAI,YAAY,WAAW,GACzB,MAAM,IAAI,MACR,qFAAqF,YAAY,OAAO,EAC1G;CAGF,OAAO,YAAY,GAAG;AACxB;;;;;AAkCA,SAAgB,2BAId,YACsD;CACtD,SAAS,YACP,YACqD;EACrD,OAAO;CACT;CAEA,OAAO;EACL;EACA,mBAAmB,yBAAyB,UAAU;CACxD;AACF"}

package/dist/create-config/render-state.d.cts

@@ -0,0 +1,120 @@
+import { LayoutResourceKey, ResourceDefinition } from "../resource.cjs";
+import { InPropsDefinition, InPropsObject, IncludedProps, LayoutRenderProps, MergedLayoutInProps } from "../props.cjs";
+import { ComposableComponents, CreateLayoutComposable } from "@jfdevelops/react-layout-composables";
+import { JSX } from "react";
+
+//#region src/create-config/render-state.d.ts
+declare const deferredRenderStateSymbol: unique symbol;
+declare const lazyRenderStateSymbol: unique symbol;
+declare const definedRenderStateSymbol: unique symbol;
+declare const definedResourceLayoutComponentSymbol: unique symbol;
+/** Runtime-compatible render-state shape used when inspecting lazy modules. */
+type AnyRenderStateDefinition = {
+  composables?: (create: CreateLayoutComposable<any>) => ComposableComponents;
+  props?: {
+    include?: Record<string, unknown>;
+    custom?: InPropsObject;
+  };
+  render: (props: any, context: any) => JSX.Element;
+  state?: string;
+};
+/** An inline state whose first render is scheduled through `React.lazy`. */
+type DeferredRenderState<Definition extends AnyRenderStateDefinition> = {
+  readonly [deferredRenderStateSymbol]: Definition;
+};
+/** A state definition supplied by a separately imported module. */
+type LazyRenderState<Definition extends AnyRenderStateDefinition> = {
+  readonly [lazyRenderStateSymbol]: () => Promise<Record<string, unknown>>;
+  readonly definition?: Definition;
+};
+/** Callback shorthand for a render state with no local configuration. */
+type RenderStateCallback = (props: any, context: any) => JSX.Element;
+/**
+ * Defines state-local composable components with a `create` helper narrowed to
+ * the resources bound to the surrounding builder.
+ */
+type RenderStateComposablesDefinition<Resources extends ReadonlyArray<ResourceDefinition>, Composables extends ComposableComponents> = (create: CreateLayoutComposable<LayoutResourceKey<Resources>>) => Composables;
+/**
+ * Defines reusable layout-level composables while preserving their inferred
+ * names, props, and bound resource union.
+ */
+type LayoutComposablesDefinition<Resources extends ReadonlyArray<ResourceDefinition>, Composables extends ComposableComponents> = RenderStateComposablesDefinition<Resources, Composables>;
+type BuilderRenderComposables<Composables extends ComposableComponents> = [keyof Composables] extends [never] ? undefined : Composables;
+/** Values available as the second argument of a created state's `render`. */
+type RenderStateContext<Composables extends ComposableComponents> = {
+  composables: BuilderRenderComposables<Composables>;
+  retry?: () => void;
+};
+/**
+ * Resolves one state's custom props and explicitly included option/composable
+ * props to the values received by its render callback.
+ */
+type RenderStateProps<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>, Composables extends ComposableComponents, IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>>, CustomProps extends InPropsObject> = LayoutRenderProps<Resources, Options, Composables, IncludeProps, CustomProps>;
+type TypedRenderStateDefinition<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>, State extends string, CustomProps extends InPropsObject, Composables extends ComposableComponents, IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>>> = {
+  composables?: RenderStateComposablesDefinition<Resources, Composables>;
+  props?: {
+    include?: IncludeProps;
+    custom?: CustomProps;
+  };
+  render: (props: RenderStateProps<Resources, Options, Composables, IncludeProps, CustomProps>, context: RenderStateContext<Composables>) => JSX.Element;
+  state: State;
+};
+type NormalizeRenderStateDefinition<Input> = Input extends DeferredRenderState<infer Definition> ? Definition : Input extends RenderStateCallback ? {
+  render: Input;
+  state: 'default';
+} : Input extends AnyRenderStateDefinition ? Input : never;
+type StateName<Definition> = Definition extends DeferredRenderState<infer DeferredDefinition> ? StateName<DeferredDefinition> : Definition extends {
+  state?: infer State extends string;
+} ? State : 'default';
+/**
+ * A spreadable state entry keyed by its literal state name. Spreading this into
+ * `layout.render` is what creates compound members such as `Users.Loading`.
+ */
+type RenderStateFragment<Definition> = { [State in StateName<NormalizeRenderStateDefinition<Definition>>]: Definition } & {
+  readonly [definedRenderStateSymbol]: NormalizeRenderStateDefinition<Definition>;
+};
+type DefinedRenderStateFromModule<Module> = Extract<Module[keyof Module], {
+  readonly [definedRenderStateSymbol]: AnyRenderStateDefinition;
+}>[typeof definedRenderStateSymbol];
+/**
+ * Creates independently typed render-state fragments.
+ *
+ * - Calling it directly creates an eager state.
+ * - `.defer(...)` schedules an inline definition through `React.lazy`, but
+ *   does not create a separate JavaScript chunk.
+ * - `.lazy(() => import(...))` imports a complete named state definition as a
+ *   separate chunk.
+ */
+type CreateRenderState<Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources> = {}> = {
+  <const State extends string = 'default', const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>>;
+  <const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>, 'state'>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>>;
+  <const Render extends RenderStateCallback>(render: Render): RenderStateFragment<Render>;
+  defer<const State extends string = 'default', const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>>>;
+  defer<const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>, 'state'>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>>>;
+  defer<const Render extends RenderStateCallback>(render: Render): RenderStateFragment<DeferredRenderState<{
+    render: Render;
+    state: 'default';
+  }>>;
+  lazy<Module extends Record<string, unknown>>(load: () => Promise<Module>): LazyRenderState<DefinedRenderStateFromModule<Module>>;
+};
+/** Inputs used internally to bind resource and option types to a state builder. */
+type CreateRenderStateBuilderArguments<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = {
+  options: Options;
+  resources: Resources;
+};
+/** The state factory produced for a particular resource and option definition. */
+type CreateRenderStateBuilderResult<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = CreateRenderState<Resources, Options>;
+/** Identity helper that contextually types a reusable composables callback. */
+type DefineLayoutComposables<Resources extends ReadonlyArray<ResourceDefinition>> = <const Composables extends ComposableComponents>(definition: LayoutComposablesDefinition<Resources, Composables>) => LayoutComposablesDefinition<Resources, Composables>;
+/** Public cross-file building blocks returned by a defined layout builder. */
+type CreateLayoutBuildingBlocks<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = {
+  composables: DefineLayoutComposables<Resources>;
+  createRenderState: CreateRenderState<Resources, Options>;
+};
+/** Resource and option bindings used to create layout building blocks. */
+type CreateLayoutBuildingBlocksArguments<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = CreateRenderStateBuilderArguments<Resources, Options>;
+/** Layout helpers produced for the supplied resource and option bindings. */
+type CreateLayoutBuildingBlocksResult<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = CreateLayoutBuildingBlocks<Resources, Options>;
+//#endregion
+export { AnyRenderStateDefinition, CreateLayoutBuildingBlocks, CreateLayoutBuildingBlocksArguments, CreateLayoutBuildingBlocksResult, CreateRenderState, CreateRenderStateBuilderArguments, CreateRenderStateBuilderResult, DeferredRenderState, DefineLayoutComposables, LayoutComposablesDefinition, LazyRenderState, RenderStateCallback, RenderStateComposablesDefinition, RenderStateContext, RenderStateFragment, RenderStateProps, definedResourceLayoutComponentSymbol };
+//# sourceMappingURL=render-state.d.cts.map

package/dist/create-config/render-state.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-state.d.cts","names":[],"sources":["../../src/create-config/render-state.ts"],"mappings":"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"}

package/dist/create-config/render-state.d.mts

@@ -0,0 +1,120 @@
+import { LayoutResourceKey, ResourceDefinition } from "../resource.mjs";
+import { InPropsDefinition, InPropsObject, IncludedProps, LayoutRenderProps, MergedLayoutInProps } from "../props.mjs";
+import { ComposableComponents, CreateLayoutComposable } from "@jfdevelops/react-layout-composables";
+import { JSX } from "react";
+
+//#region src/create-config/render-state.d.ts
+declare const deferredRenderStateSymbol: unique symbol;
+declare const lazyRenderStateSymbol: unique symbol;
+declare const definedRenderStateSymbol: unique symbol;
+declare const definedResourceLayoutComponentSymbol: unique symbol;
+/** Runtime-compatible render-state shape used when inspecting lazy modules. */
+type AnyRenderStateDefinition = {
+  composables?: (create: CreateLayoutComposable<any>) => ComposableComponents;
+  props?: {
+    include?: Record<string, unknown>;
+    custom?: InPropsObject;
+  };
+  render: (props: any, context: any) => JSX.Element;
+  state?: string;
+};
+/** An inline state whose first render is scheduled through `React.lazy`. */
+type DeferredRenderState<Definition extends AnyRenderStateDefinition> = {
+  readonly [deferredRenderStateSymbol]: Definition;
+};
+/** A state definition supplied by a separately imported module. */
+type LazyRenderState<Definition extends AnyRenderStateDefinition> = {
+  readonly [lazyRenderStateSymbol]: () => Promise<Record<string, unknown>>;
+  readonly definition?: Definition;
+};
+/** Callback shorthand for a render state with no local configuration. */
+type RenderStateCallback = (props: any, context: any) => JSX.Element;
+/**
+ * Defines state-local composable components with a `create` helper narrowed to
+ * the resources bound to the surrounding builder.
+ */
+type RenderStateComposablesDefinition<Resources extends ReadonlyArray<ResourceDefinition>, Composables extends ComposableComponents> = (create: CreateLayoutComposable<LayoutResourceKey<Resources>>) => Composables;
+/**
+ * Defines reusable layout-level composables while preserving their inferred
+ * names, props, and bound resource union.
+ */
+type LayoutComposablesDefinition<Resources extends ReadonlyArray<ResourceDefinition>, Composables extends ComposableComponents> = RenderStateComposablesDefinition<Resources, Composables>;
+type BuilderRenderComposables<Composables extends ComposableComponents> = [keyof Composables] extends [never] ? undefined : Composables;
+/** Values available as the second argument of a created state's `render`. */
+type RenderStateContext<Composables extends ComposableComponents> = {
+  composables: BuilderRenderComposables<Composables>;
+  retry?: () => void;
+};
+/**
+ * Resolves one state's custom props and explicitly included option/composable
+ * props to the values received by its render callback.
+ */
+type RenderStateProps<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>, Composables extends ComposableComponents, IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>>, CustomProps extends InPropsObject> = LayoutRenderProps<Resources, Options, Composables, IncludeProps, CustomProps>;
+type TypedRenderStateDefinition<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>, State extends string, CustomProps extends InPropsObject, Composables extends ComposableComponents, IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>>> = {
+  composables?: RenderStateComposablesDefinition<Resources, Composables>;
+  props?: {
+    include?: IncludeProps;
+    custom?: CustomProps;
+  };
+  render: (props: RenderStateProps<Resources, Options, Composables, IncludeProps, CustomProps>, context: RenderStateContext<Composables>) => JSX.Element;
+  state: State;
+};
+type NormalizeRenderStateDefinition<Input> = Input extends DeferredRenderState<infer Definition> ? Definition : Input extends RenderStateCallback ? {
+  render: Input;
+  state: 'default';
+} : Input extends AnyRenderStateDefinition ? Input : never;
+type StateName<Definition> = Definition extends DeferredRenderState<infer DeferredDefinition> ? StateName<DeferredDefinition> : Definition extends {
+  state?: infer State extends string;
+} ? State : 'default';
+/**
+ * A spreadable state entry keyed by its literal state name. Spreading this into
+ * `layout.render` is what creates compound members such as `Users.Loading`.
+ */
+type RenderStateFragment<Definition> = { [State in StateName<NormalizeRenderStateDefinition<Definition>>]: Definition } & {
+  readonly [definedRenderStateSymbol]: NormalizeRenderStateDefinition<Definition>;
+};
+type DefinedRenderStateFromModule<Module> = Extract<Module[keyof Module], {
+  readonly [definedRenderStateSymbol]: AnyRenderStateDefinition;
+}>[typeof definedRenderStateSymbol];
+/**
+ * Creates independently typed render-state fragments.
+ *
+ * - Calling it directly creates an eager state.
+ * - `.defer(...)` schedules an inline definition through `React.lazy`, but
+ *   does not create a separate JavaScript chunk.
+ * - `.lazy(() => import(...))` imports a complete named state definition as a
+ *   separate chunk.
+ */
+type CreateRenderState<Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources> = {}> = {
+  <const State extends string = 'default', const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>>;
+  <const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>, 'state'>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>>;
+  <const Render extends RenderStateCallback>(render: Render): RenderStateFragment<Render>;
+  defer<const State extends string = 'default', const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, State, CustomProps, Composables, IncludeProps>>>;
+  defer<const CustomProps extends InPropsObject = {}, const Composables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, Composables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>, 'state'>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, Composables, IncludeProps>>>;
+  defer<const Render extends RenderStateCallback>(render: Render): RenderStateFragment<DeferredRenderState<{
+    render: Render;
+    state: 'default';
+  }>>;
+  lazy<Module extends Record<string, unknown>>(load: () => Promise<Module>): LazyRenderState<DefinedRenderStateFromModule<Module>>;
+};
+/** Inputs used internally to bind resource and option types to a state builder. */
+type CreateRenderStateBuilderArguments<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = {
+  options: Options;
+  resources: Resources;
+};
+/** The state factory produced for a particular resource and option definition. */
+type CreateRenderStateBuilderResult<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = CreateRenderState<Resources, Options>;
+/** Identity helper that contextually types a reusable composables callback. */
+type DefineLayoutComposables<Resources extends ReadonlyArray<ResourceDefinition>> = <const Composables extends ComposableComponents>(definition: LayoutComposablesDefinition<Resources, Composables>) => LayoutComposablesDefinition<Resources, Composables>;
+/** Public cross-file building blocks returned by a defined layout builder. */
+type CreateLayoutBuildingBlocks<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = {
+  composables: DefineLayoutComposables<Resources>;
+  createRenderState: CreateRenderState<Resources, Options>;
+};
+/** Resource and option bindings used to create layout building blocks. */
+type CreateLayoutBuildingBlocksArguments<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = CreateRenderStateBuilderArguments<Resources, Options>;
+/** Layout helpers produced for the supplied resource and option bindings. */
+type CreateLayoutBuildingBlocksResult<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>> = CreateLayoutBuildingBlocks<Resources, Options>;
+//#endregion
+export { AnyRenderStateDefinition, CreateLayoutBuildingBlocks, CreateLayoutBuildingBlocksArguments, CreateLayoutBuildingBlocksResult, CreateRenderState, CreateRenderStateBuilderArguments, CreateRenderStateBuilderResult, DeferredRenderState, DefineLayoutComposables, LayoutComposablesDefinition, LazyRenderState, RenderStateCallback, RenderStateComposablesDefinition, RenderStateContext, RenderStateFragment, RenderStateProps, definedResourceLayoutComponentSymbol };
+//# sourceMappingURL=render-state.d.mts.map

package/dist/create-config/render-state.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-state.d.mts","names":[],"sources":["../../src/create-config/render-state.ts"],"mappings":"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"}

package/dist/create-config/render-state.mjs

@@ -0,0 +1,68 @@
+//#region src/create-config/render-state.ts
+const deferredRenderStateSymbol = Symbol("deferredRenderState");
+const lazyRenderStateSymbol = Symbol("lazyRenderState");
+const definedRenderStateSymbol = Symbol.for("@jfdevelops/react-layout/render-state");
+const definedResourceLayoutComponentSymbol = Symbol.for("@jfdevelops/react-layout/resource-layout-component");
+function normalizeDefinition(input) {
+	return typeof input === "function" ? {
+		render: input,
+		state: "default"
+	} : input;
+}
+function toFragment(definition) {
+	const fragment = { [definition.state ?? "default"]: definition };
+	Object.defineProperty(fragment, definedRenderStateSymbol, {
+		enumerable: false,
+		value: definition
+	});
+	return fragment;
+}
+/**
+* Creates a state factory whose `props.include` keys are constrained by the
+* supplied resources and options.
+*/
+function createRenderStateBuilder(_arguments) {
+	function createRenderState(input) {
+		return toFragment(normalizeDefinition(input));
+	}
+	createRenderState.defer = (input) => {
+		const definition = normalizeDefinition(input);
+		return { [definition.state ?? "default"]: { [deferredRenderStateSymbol]: definition } };
+	};
+	createRenderState.lazy = (load) => ({ [lazyRenderStateSymbol]: load });
+	return createRenderState;
+}
+/** Type guard for states created with `createRenderState.defer(...)`. */
+function isDeferredRenderState(value) {
+	return typeof value === "object" && value !== null && deferredRenderStateSymbol in value;
+}
+/** Type guard for states created with `createRenderState.lazy(...)`. */
+function isLazyRenderState(value) {
+	return typeof value === "object" && value !== null && lazyRenderStateSymbol in value;
+}
+/**
+* Selects the single state definition exported by a lazy module. Throws when
+* the module exports none or more than one, avoiding ambiguous selection.
+*/
+function findDefinedRenderState(module) {
+	const definitions = Object.values(module).filter((value) => typeof value === "object" && value !== null && definedRenderStateSymbol in value);
+	if (definitions.length !== 1) throw new Error(`A lazy render-state module must export exactly one defined render state; received ${definitions.length}.`);
+	return definitions[0][definedRenderStateSymbol];
+}
+/**
+* Creates the reusable `composables` and `createRenderState` helpers without
+* introducing an identity wrapper around the layout object itself.
+*/
+function createLayoutBuildingBlocks(arguments_) {
+	function composables(definition) {
+		return definition;
+	}
+	return {
+		composables,
+		createRenderState: createRenderStateBuilder(arguments_)
+	};
+}
+
+//#endregion
+export { createLayoutBuildingBlocks, deferredRenderStateSymbol, definedResourceLayoutComponentSymbol, findDefinedRenderState, isDeferredRenderState, isLazyRenderState, lazyRenderStateSymbol };
+//# sourceMappingURL=render-state.mjs.map

package/dist/create-config/render-state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-state.mjs","names":[],"sources":["../../src/create-config/render-state.ts"],"sourcesContent":["import type { JSX } from 'react';\nimport type {\n  ComposableComponents,\n  CreateLayoutComposable,\n} from '@jfdevelops/react-layout-composables';\nimport type { InPropsObject } from '../props';\nimport type {\n  IncludedProps,\n  InPropsDefinition,\n  LayoutRenderProps,\n  MergedLayoutInProps,\n} from '../props';\nimport type { LayoutResourceKey, ResourceDefinition } from '../resource';\n\nexport const deferredRenderStateSymbol: unique symbol = Symbol(\n  'deferredRenderState',\n) as never;\nexport const lazyRenderStateSymbol: unique symbol = Symbol(\n  'lazyRenderState',\n) as never;\nexport const definedRenderStateSymbol: unique symbol = Symbol.for(\n  '@jfdevelops/react-layout/render-state',\n) as never;\nexport const definedResourceLayoutComponentSymbol: unique symbol = Symbol.for(\n  '@jfdevelops/react-layout/resource-layout-component',\n) as never;\n\n/** Runtime-compatible render-state shape used when inspecting lazy modules. */\nexport type AnyRenderStateDefinition = {\n  composables?: (create: CreateLayoutComposable<any>) => ComposableComponents;\n  props?: {\n    include?: Record<string, unknown>;\n    custom?: InPropsObject;\n  };\n  render: (props: any, context: any) => JSX.Element;\n  state?: string;\n};\n\n/** An inline state whose first render is scheduled through `React.lazy`. */\nexport type DeferredRenderState<Definition extends AnyRenderStateDefinition> = {\n  readonly [deferredRenderStateSymbol]: Definition;\n};\n\n/** A state definition supplied by a separately imported module. */\nexport type LazyRenderState<Definition extends AnyRenderStateDefinition> = {\n  readonly [lazyRenderStateSymbol]: () => Promise<Record<string, unknown>>;\n  readonly definition?: Definition;\n};\n\n/** Callback shorthand for a render state with no local configuration. */\nexport type RenderStateCallback = (props: any, context: any) => JSX.Element;\n\n/**\n * Defines state-local composable components with a `create` helper narrowed to\n * the resources bound to the surrounding builder.\n */\nexport type RenderStateComposablesDefinition<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Composables extends ComposableComponents,\n> = (\n  create: CreateLayoutComposable<LayoutResourceKey<Resources>>,\n) => Composables;\n\n/**\n * Defines reusable layout-level composables while preserving their inferred\n * names, props, and bound resource union.\n */\nexport type LayoutComposablesDefinition<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Composables extends ComposableComponents,\n> = RenderStateComposablesDefinition<Resources, Composables>;\n\ntype BuilderRenderComposables<Composables extends ComposableComponents> = [\n  keyof Composables,\n] extends [never]\n  ? undefined\n  : Composables;\n\n/** Values available as the second argument of a created state's `render`. */\nexport type RenderStateContext<\n  Composables extends ComposableComponents,\n> = {\n  composables: BuilderRenderComposables<Composables>;\n  retry?: () => void;\n};\n\n/**\n * Resolves one state's custom props and explicitly included option/composable\n * props to the values received by its render callback.\n */\nexport type RenderStateProps<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n  Composables extends ComposableComponents,\n  IncludeProps extends IncludedProps<\n    MergedLayoutInProps<Resources, Options, Composables>\n  >,\n  CustomProps extends InPropsObject,\n> = LayoutRenderProps<\n  Resources,\n  Options,\n  Composables,\n  IncludeProps,\n  CustomProps\n>;\n\ntype TypedRenderStateDefinition<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n  State extends string,\n  CustomProps extends InPropsObject,\n  Composables extends ComposableComponents,\n  IncludeProps extends IncludedProps<\n    MergedLayoutInProps<Resources, Options, Composables>\n  >,\n> = {\n  composables?: RenderStateComposablesDefinition<Resources, Composables>;\n  props?: {\n    include?: IncludeProps;\n    custom?: CustomProps;\n  };\n  render: (\n    props: RenderStateProps<\n      Resources,\n      Options,\n      Composables,\n      IncludeProps,\n      CustomProps\n    >,\n    context: RenderStateContext<Composables>,\n  ) => JSX.Element;\n  state: State;\n};\n\ntype NormalizeRenderStateDefinition<Input> =\n  Input extends DeferredRenderState<infer Definition>\n    ? Definition\n    : Input extends RenderStateCallback\n      ? { render: Input; state: 'default' }\n      : Input extends AnyRenderStateDefinition\n        ? Input\n        : never;\n\ntype StateName<Definition> = Definition extends DeferredRenderState<\n  infer DeferredDefinition\n>\n  ? StateName<DeferredDefinition>\n  : Definition extends { state?: infer State extends string }\n    ? State\n    : 'default';\n\n/**\n * A spreadable state entry keyed by its literal state name. Spreading this into\n * `layout.render` is what creates compound members such as `Users.Loading`.\n */\nexport type RenderStateFragment<Definition> = {\n  [State in StateName<NormalizeRenderStateDefinition<Definition>>]: Definition;\n} & {\n  readonly [definedRenderStateSymbol]: NormalizeRenderStateDefinition<Definition>;\n};\n\ntype DefinedRenderStateFromModule<Module> = Extract<\n  Module[keyof Module],\n  { readonly [definedRenderStateSymbol]: AnyRenderStateDefinition }\n>[typeof definedRenderStateSymbol];\n\n/**\n * Creates independently typed render-state fragments.\n *\n * - Calling it directly creates an eager state.\n * - `.defer(...)` schedules an inline definition through `React.lazy`, but\n *   does not create a separate JavaScript chunk.\n * - `.lazy(() => import(...))` imports a complete named state definition as a\n *   separate chunk.\n */\nexport type CreateRenderState<\n  Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources> = {},\n> = {\n  <\n    const State extends string = 'default',\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      Composables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      Composables,\n      IncludeProps\n    >\n  >;\n  <\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        Composables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      'default',\n      CustomProps,\n      Composables,\n      IncludeProps\n    >\n  >;\n  <const Render extends RenderStateCallback>(\n    render: Render,\n  ): RenderStateFragment<Render>;\n  defer<\n    const State extends string = 'default',\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      Composables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        State,\n        CustomProps,\n        Composables,\n        IncludeProps\n      >\n    >\n  >;\n  defer<\n    const CustomProps extends InPropsObject = {},\n    const Composables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<Resources, Options, Composables>\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        Composables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        Composables,\n        IncludeProps\n      >\n    >\n  >;\n  defer<const Render extends RenderStateCallback>(\n    render: Render,\n  ): RenderStateFragment<DeferredRenderState<{ render: Render; state: 'default' }>>;\n  lazy<Module extends Record<string, unknown>>(\n    load: () => Promise<Module>,\n  ): LazyRenderState<DefinedRenderStateFromModule<Module>>;\n};\n\nfunction normalizeDefinition(\n  input: AnyRenderStateDefinition | RenderStateCallback,\n): AnyRenderStateDefinition {\n  return typeof input === 'function'\n    ? { render: input, state: 'default' }\n    : input;\n}\n\nfunction toFragment<Definition extends AnyRenderStateDefinition>(\n  definition: Definition,\n) {\n  const fragment = {\n    [definition.state ?? 'default']: definition,\n  } as RenderStateFragment<Definition>;\n\n  Object.defineProperty(fragment, definedRenderStateSymbol, {\n    enumerable: false,\n    value: definition,\n  });\n\n  return fragment;\n}\n\n/** Inputs used internally to bind resource and option types to a state builder. */\nexport type CreateRenderStateBuilderArguments<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = {\n  options: Options;\n  resources: Resources;\n};\n\n/** The state factory produced for a particular resource and option definition. */\nexport type CreateRenderStateBuilderResult<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = CreateRenderState<Resources, Options>;\n\n/**\n * Creates a state factory whose `props.include` keys are constrained by the\n * supplied resources and options.\n */\nexport function createRenderStateBuilder<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n>(\n  _arguments: CreateRenderStateBuilderArguments<Resources, Options>,\n): CreateRenderStateBuilderResult<Resources, Options> {\n  function createRenderState(\n    input: AnyRenderStateDefinition | RenderStateCallback,\n  ) {\n    return toFragment(normalizeDefinition(input));\n  }\n\n  createRenderState.defer = (\n    input: AnyRenderStateDefinition | RenderStateCallback,\n  ) => {\n    const definition = normalizeDefinition(input);\n\n    return {\n      [definition.state ?? 'default']: {\n        [deferredRenderStateSymbol]: definition,\n      },\n    };\n  };\n  createRenderState.lazy = (\n    load: () => Promise<Record<string, unknown>>,\n  ) => ({\n    [lazyRenderStateSymbol]: load,\n  });\n\n  return createRenderState as CreateRenderStateBuilderResult<Resources, Options>;\n}\n\n/** Type guard for states created with `createRenderState.defer(...)`. */\nexport function isDeferredRenderState(\n  value: unknown,\n): value is DeferredRenderState<AnyRenderStateDefinition> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    deferredRenderStateSymbol in value\n  );\n}\n\n/** Type guard for states created with `createRenderState.lazy(...)`. */\nexport function isLazyRenderState(\n  value: unknown,\n): value is LazyRenderState<AnyRenderStateDefinition> {\n  return (\n    typeof value === 'object' && value !== null && lazyRenderStateSymbol in value\n  );\n}\n\n/**\n * Selects the single state definition exported by a lazy module. Throws when\n * the module exports none or more than one, avoiding ambiguous selection.\n */\nexport function findDefinedRenderState(\n  module: Record<string, unknown>,\n): AnyRenderStateDefinition {\n  const definitions = Object.values(module).filter(\n    (value) =>\n      typeof value === 'object' && value !== null && definedRenderStateSymbol in value,\n  ) as Array<Record<typeof definedRenderStateSymbol, AnyRenderStateDefinition>>;\n\n  if (definitions.length !== 1) {\n    throw new Error(\n      `A lazy render-state module must export exactly one defined render state; received ${definitions.length}.`,\n    );\n  }\n\n  return definitions[0][definedRenderStateSymbol];\n}\n\n/** Identity helper that contextually types a reusable composables callback. */\nexport type DefineLayoutComposables<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n> = <const Composables extends ComposableComponents>(\n  definition: LayoutComposablesDefinition<Resources, Composables>,\n) => LayoutComposablesDefinition<Resources, Composables>;\n\n/** Public cross-file building blocks returned by a defined layout builder. */\nexport type CreateLayoutBuildingBlocks<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = {\n  composables: DefineLayoutComposables<Resources>;\n  createRenderState: CreateRenderState<Resources, Options>;\n};\n\n/** Resource and option bindings used to create layout building blocks. */\nexport type CreateLayoutBuildingBlocksArguments<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = CreateRenderStateBuilderArguments<Resources, Options>;\n\n/** Layout helpers produced for the supplied resource and option bindings. */\nexport type CreateLayoutBuildingBlocksResult<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n> = CreateLayoutBuildingBlocks<Resources, Options>;\n\n/**\n * Creates the reusable `composables` and `createRenderState` helpers without\n * introducing an identity wrapper around the layout object itself.\n */\nexport function createLayoutBuildingBlocks<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n  Options extends InPropsDefinition<Resources>,\n>(\n  arguments_: CreateLayoutBuildingBlocksArguments<Resources, Options>,\n): CreateLayoutBuildingBlocksResult<Resources, Options> {\n  function composables<const Composables extends ComposableComponents>(\n    definition: LayoutComposablesDefinition<Resources, Composables>,\n  ): LayoutComposablesDefinition<Resources, Composables> {\n    return definition;\n  }\n\n  return {\n    composables,\n    createRenderState: createRenderStateBuilder(arguments_),\n  };\n}\n\n/** Preserves a bound resource tuple for consumers that need to re-export it. */\nexport type BoundResources<\n  Resources extends ReadonlyArray<ResourceDefinition>,\n> = Resources;\n"],"mappings":";AAcA,MAAa,4BAA2C,OACtD,qBACF;AACA,MAAa,wBAAuC,OAClD,iBACF;AACA,MAAa,2BAA0C,OAAO,IAC5D,uCACF;AACA,MAAa,uCAAsD,OAAO,IACxE,oDACF;AAqRA,SAAS,oBACP,OAC0B;CAC1B,OAAO,OAAO,UAAU,aACpB;EAAE,QAAQ;EAAO,OAAO;CAAU,IAClC;AACN;AAEA,SAAS,WACP,YACA;CACA,MAAM,WAAW,GACd,WAAW,SAAS,YAAY,WACnC;CAEA,OAAO,eAAe,UAAU,0BAA0B;EACxD,YAAY;EACZ,OAAO;CACT,CAAC;CAED,OAAO;AACT;;;;;AAqBA,SAAgB,yBAId,YACoD;CACpD,SAAS,kBACP,OACA;EACA,OAAO,WAAW,oBAAoB,KAAK,CAAC;CAC9C;CAEA,kBAAkB,SAChB,UACG;EACH,MAAM,aAAa,oBAAoB,KAAK;EAE5C,OAAO,GACJ,WAAW,SAAS,YAAY,GAC9B,4BAA4B,WAC/B,EACF;CACF;CACA,kBAAkB,QAChB,UACI,GACH,wBAAwB,KAC3B;CAEA,OAAO;AACT;;AAGA,SAAgB,sBACd,OACwD;CACxD,OACE,OAAO,UAAU,YACjB,UAAU,QACV,6BAA6B;AAEjC;;AAGA,SAAgB,kBACd,OACoD;CACpD,OACE,OAAO,UAAU,YAAY,UAAU,QAAQ,yBAAyB;AAE5E;;;;;AAMA,SAAgB,uBACd,QAC0B;CAC1B,MAAM,cAAc,OAAO,OAAO,MAAM,EAAE,QACvC,UACC,OAAO,UAAU,YAAY,UAAU,QAAQ,4BAA4B,KAC/E;CAEA,IAAI,YAAY,WAAW,GACzB,MAAM,IAAI,MACR,qFAAqF,YAAY,OAAO,EAC1G;CAGF,OAAO,YAAY,GAAG;AACxB;;;;;AAkCA,SAAgB,2BAId,YACsD;CACtD,SAAS,YACP,YACqD;EACrD,OAAO;CACT;CAEA,OAAO;EACL;EACA,mBAAmB,yBAAyB,UAAU;CACxD;AACF"}