@jfdevelops/react-layout 0.24.3 → 1.0.0

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

@@ -0,0 +1,62 @@
+
+//#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];
+}
+
+//#endregion
+exports.createRenderStateBuilder = createRenderStateBuilder;
+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  SharedComposables extends ComposableComponents,\n  StateComposables extends ComposableComponents,\n  IncludeProps extends IncludedProps<\n    MergedLayoutInProps<\n      Resources,\n      Options,\n      SharedComposables & StateComposables\n    >\n  >,\n> = {\n  composables?: RenderStateComposablesDefinition<Resources, StateComposables>;\n  props?: {\n    include?: IncludeProps;\n    custom?: CustomProps;\n  };\n  render: (\n    props: RenderStateProps<\n      Resources,\n      Options,\n      SharedComposables & StateComposables,\n      IncludeProps,\n      CustomProps\n    >,\n    context: RenderStateContext<SharedComposables & StateComposables>,\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  SharedComposables extends ComposableComponents = {},\n> = {\n  <\n    const State extends string = 'default',\n    const CustomProps extends InPropsObject = {},\n    const StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      SharedComposables,\n      StateComposables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      SharedComposables,\n      StateComposables,\n      IncludeProps\n    >\n  >;\n  <\n    const CustomProps extends InPropsObject = {},\n    const StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        SharedComposables,\n        StateComposables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      'default',\n      CustomProps,\n      SharedComposables,\n      StateComposables,\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 StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      SharedComposables,\n      StateComposables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        State,\n        CustomProps,\n        SharedComposables,\n        StateComposables,\n        IncludeProps\n      >\n    >\n  >;\n  defer<\n    const CustomProps extends InPropsObject = {},\n    const StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        SharedComposables,\n        StateComposables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        SharedComposables,\n        StateComposables,\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  SharedComposables extends ComposableComponents = {},\n> = {\n  /** Shared composables whose components and preset props every state can use. */\n  composables?: LayoutComposablesDefinition<Resources, SharedComposables>;\n  /** Option props that individual states can expose through `props.include`. */\n  options: Options;\n  /** Resources used to constrain composable names and resource-specific props. */\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  SharedComposables extends ComposableComponents = {},\n> = CreateRenderState<Resources, Options, SharedComposables>;\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  SharedComposables extends ComposableComponents = {},\n>(\n  _arguments: CreateRenderStateBuilderArguments<\n    Resources,\n    Options,\n    SharedComposables\n  >,\n): CreateRenderStateBuilderResult<Resources, Options, SharedComposables> {\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<\n    Resources,\n    Options,\n    SharedComposables\n  >;\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;AAmTA,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;;;;;AA2BA,SAAgB,yBAKd,YAKuE;CACvE,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;AAKT;;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"}

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

@@ -0,0 +1,121 @@
+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, SharedComposables extends ComposableComponents, StateComposables extends ComposableComponents, IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>>> = {
+  composables?: RenderStateComposablesDefinition<Resources, StateComposables>;
+  props?: {
+    include?: IncludeProps;
+    custom?: CustomProps;
+  };
+  render: (props: RenderStateProps<Resources, Options, SharedComposables & StateComposables, IncludeProps, CustomProps>, context: RenderStateContext<SharedComposables & StateComposables>) => 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> = {}, SharedComposables extends ComposableComponents = {}> = {
+  <const State extends string = 'default', const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>>;
+  <const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, IncludeProps>, 'state'>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, IncludeProps>>;
+  <const Render extends RenderStateCallback>(render: Render): RenderStateFragment<Render>;
+  defer<const State extends string = 'default', const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>>>;
+  defer<const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, IncludeProps>, 'state'>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, 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>, SharedComposables extends ComposableComponents = {}> = {
+  /** Shared composables whose components and preset props every state can use. */composables?: LayoutComposablesDefinition<Resources, SharedComposables>; /** Option props that individual states can expose through `props.include`. */
+  options: Options; /** Resources used to constrain composable names and resource-specific props. */
+  resources: Resources;
+};
+/** The state factory produced for a particular resource and option definition. */
+type CreateRenderStateBuilderResult<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>, SharedComposables extends ComposableComponents = {}> = CreateRenderState<Resources, Options, SharedComposables>;
+/** 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,121 @@
+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, SharedComposables extends ComposableComponents, StateComposables extends ComposableComponents, IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>>> = {
+  composables?: RenderStateComposablesDefinition<Resources, StateComposables>;
+  props?: {
+    include?: IncludeProps;
+    custom?: CustomProps;
+  };
+  render: (props: RenderStateProps<Resources, Options, SharedComposables & StateComposables, IncludeProps, CustomProps>, context: RenderStateContext<SharedComposables & StateComposables>) => 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> = {}, SharedComposables extends ComposableComponents = {}> = {
+  <const State extends string = 'default', const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>>;
+  <const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, IncludeProps>, 'state'>): RenderStateFragment<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, IncludeProps>>;
+  <const Render extends RenderStateCallback>(render: Render): RenderStateFragment<Render>;
+  defer<const State extends string = 'default', const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, State, CustomProps, SharedComposables, StateComposables, IncludeProps>>>;
+  defer<const CustomProps extends InPropsObject = {}, const StateComposables extends ComposableComponents = {}, const IncludeProps extends IncludedProps<MergedLayoutInProps<Resources, Options, SharedComposables & StateComposables>> = {}>(definition: Omit<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, IncludeProps>, 'state'>): RenderStateFragment<DeferredRenderState<TypedRenderStateDefinition<Resources, Options, 'default', CustomProps, SharedComposables, StateComposables, 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>, SharedComposables extends ComposableComponents = {}> = {
+  /** Shared composables whose components and preset props every state can use. */composables?: LayoutComposablesDefinition<Resources, SharedComposables>; /** Option props that individual states can expose through `props.include`. */
+  options: Options; /** Resources used to constrain composable names and resource-specific props. */
+  resources: Resources;
+};
+/** The state factory produced for a particular resource and option definition. */
+type CreateRenderStateBuilderResult<Resources extends ReadonlyArray<ResourceDefinition>, Options extends InPropsDefinition<Resources>, SharedComposables extends ComposableComponents = {}> = CreateRenderState<Resources, Options, SharedComposables>;
+/** 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,55 @@
+//#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];
+}
+
+//#endregion
+export { createRenderStateBuilder, 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  SharedComposables extends ComposableComponents,\n  StateComposables extends ComposableComponents,\n  IncludeProps extends IncludedProps<\n    MergedLayoutInProps<\n      Resources,\n      Options,\n      SharedComposables & StateComposables\n    >\n  >,\n> = {\n  composables?: RenderStateComposablesDefinition<Resources, StateComposables>;\n  props?: {\n    include?: IncludeProps;\n    custom?: CustomProps;\n  };\n  render: (\n    props: RenderStateProps<\n      Resources,\n      Options,\n      SharedComposables & StateComposables,\n      IncludeProps,\n      CustomProps\n    >,\n    context: RenderStateContext<SharedComposables & StateComposables>,\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  SharedComposables extends ComposableComponents = {},\n> = {\n  <\n    const State extends string = 'default',\n    const CustomProps extends InPropsObject = {},\n    const StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      SharedComposables,\n      StateComposables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      SharedComposables,\n      StateComposables,\n      IncludeProps\n    >\n  >;\n  <\n    const CustomProps extends InPropsObject = {},\n    const StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        SharedComposables,\n        StateComposables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    TypedRenderStateDefinition<\n      Resources,\n      Options,\n      'default',\n      CustomProps,\n      SharedComposables,\n      StateComposables,\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 StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: TypedRenderStateDefinition<\n      Resources,\n      Options,\n      State,\n      CustomProps,\n      SharedComposables,\n      StateComposables,\n      IncludeProps\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        State,\n        CustomProps,\n        SharedComposables,\n        StateComposables,\n        IncludeProps\n      >\n    >\n  >;\n  defer<\n    const CustomProps extends InPropsObject = {},\n    const StateComposables extends ComposableComponents = {},\n    const IncludeProps extends IncludedProps<\n      MergedLayoutInProps<\n        Resources,\n        Options,\n        SharedComposables & StateComposables\n      >\n    > = {},\n  >(\n    definition: Omit<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        SharedComposables,\n        StateComposables,\n        IncludeProps\n      >,\n      'state'\n    >,\n  ): RenderStateFragment<\n    DeferredRenderState<\n      TypedRenderStateDefinition<\n        Resources,\n        Options,\n        'default',\n        CustomProps,\n        SharedComposables,\n        StateComposables,\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  SharedComposables extends ComposableComponents = {},\n> = {\n  /** Shared composables whose components and preset props every state can use. */\n  composables?: LayoutComposablesDefinition<Resources, SharedComposables>;\n  /** Option props that individual states can expose through `props.include`. */\n  options: Options;\n  /** Resources used to constrain composable names and resource-specific props. */\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  SharedComposables extends ComposableComponents = {},\n> = CreateRenderState<Resources, Options, SharedComposables>;\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  SharedComposables extends ComposableComponents = {},\n>(\n  _arguments: CreateRenderStateBuilderArguments<\n    Resources,\n    Options,\n    SharedComposables\n  >,\n): CreateRenderStateBuilderResult<Resources, Options, SharedComposables> {\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<\n    Resources,\n    Options,\n    SharedComposables\n  >;\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;AAmTA,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;;;;;AA2BA,SAAgB,yBAKd,YAKuE;CACvE,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;AAKT;;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"}

package/dist/errors/resource-state-error.cjs

@@ -0,0 +1,29 @@
+
+//#region src/errors/resource-state-error.ts
+/** Identifies a failed dynamic import for a resource layout or render state. */
+var ResourceModuleLoadError = class extends Error {
+	resource;
+	code = "resourceModuleLoad";
+	constructor(resource, cause) {
+		super(`Unable to load resource module "${resource}"`, { cause });
+		this.resource = resource;
+		this.name = "ResourceModuleLoadError";
+	}
+};
+/** Wraps an exception thrown while rendering a named resource state. */
+var ResourceRenderError = class extends Error {
+	resource;
+	state;
+	code = "resourceRender";
+	constructor(resource, state, cause) {
+		super(`Unable to render resource "${resource}" state "${state}"`, { cause });
+		this.resource = resource;
+		this.state = state;
+		this.name = "ResourceRenderError";
+	}
+};
+
+//#endregion
+exports.ResourceModuleLoadError = ResourceModuleLoadError;
+exports.ResourceRenderError = ResourceRenderError;
+//# sourceMappingURL=resource-state-error.cjs.map

package/dist/errors/resource-state-error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-state-error.cjs","names":[],"sources":["../../src/errors/resource-state-error.ts"],"sourcesContent":["/** Identifies a failed dynamic import for a resource layout or render state. */\nexport class ResourceModuleLoadError extends Error {\n  readonly code = 'resourceModuleLoad';\n\n  constructor(\n    readonly resource: string,\n    cause: unknown,\n  ) {\n    super(`Unable to load resource module \"${resource}\"`, { cause });\n    this.name = 'ResourceModuleLoadError';\n  }\n}\n\n/** Wraps an exception thrown while rendering a named resource state. */\nexport class ResourceRenderError extends Error {\n  readonly code = 'resourceRender';\n\n  constructor(\n    readonly resource: string,\n    readonly state: string,\n    cause: unknown,\n  ) {\n    super(`Unable to render resource \"${resource}\" state \"${state}\"`, {\n      cause,\n    });\n    this.name = 'ResourceRenderError';\n  }\n}\n\n/** Library errors that can trigger a configured resource `Error` state. */\nexport type ResourceStateError =\n  | ResourceModuleLoadError\n  | ResourceRenderError;\n"],"mappings":";;;AACA,IAAa,0BAAb,cAA6C,MAAM;CAItC;CAHX,AAAS,OAAO;CAEhB,YACE,AAAS,UACT,OACA;EACA,MAAM,mCAAmC,SAAS,IAAI,EAAE,MAAM,CAAC;EAHtD;EAIT,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAIlC;CACA;CAJX,AAAS,OAAO;CAEhB,YACE,AAAS,UACT,AAAS,OACT,OACA;EACA,MAAM,8BAA8B,SAAS,WAAW,MAAM,IAAI,EAChE,MACF,CAAC;EANQ;EACA;EAMT,KAAK,OAAO;CACd;AACF"}

package/dist/errors/resource-state-error.d.cts

@@ -0,0 +1,19 @@
+//#region src/errors/resource-state-error.d.ts
+/** Identifies a failed dynamic import for a resource layout or render state. */
+declare class ResourceModuleLoadError extends Error {
+  readonly resource: string;
+  readonly code = "resourceModuleLoad";
+  constructor(resource: string, cause: unknown);
+}
+/** Wraps an exception thrown while rendering a named resource state. */
+declare class ResourceRenderError extends Error {
+  readonly resource: string;
+  readonly state: string;
+  readonly code = "resourceRender";
+  constructor(resource: string, state: string, cause: unknown);
+}
+/** Library errors that can trigger a configured resource `Error` state. */
+type ResourceStateError = ResourceModuleLoadError | ResourceRenderError;
+//#endregion
+export { ResourceModuleLoadError, ResourceRenderError, ResourceStateError };
+//# sourceMappingURL=resource-state-error.d.cts.map

package/dist/errors/resource-state-error.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-state-error.d.cts","names":[],"sources":["../../src/errors/resource-state-error.ts"],"mappings":";;cACa,uBAAA,SAAgC,KAAK;EAAA,SAIrC,QAAA;EAAA,SAHF,IAAA;cAGE,QAAA,UACT,KAAA;AAAA;;cAQS,mBAAA,SAA4B,KAAK;EAAA,SAIjC,QAAA;EAAA,SACA,KAAA;EAAA,SAJF,IAAA;cAGE,QAAA,UACA,KAAA,UACT,KAAA;AAAA;AANJ;AAAA,KAgBY,kBAAA,GACR,uBAAA,GACA,mBAAmB"}

package/dist/errors/resource-state-error.d.mts

@@ -0,0 +1,19 @@
+//#region src/errors/resource-state-error.d.ts
+/** Identifies a failed dynamic import for a resource layout or render state. */
+declare class ResourceModuleLoadError extends Error {
+  readonly resource: string;
+  readonly code = "resourceModuleLoad";
+  constructor(resource: string, cause: unknown);
+}
+/** Wraps an exception thrown while rendering a named resource state. */
+declare class ResourceRenderError extends Error {
+  readonly resource: string;
+  readonly state: string;
+  readonly code = "resourceRender";
+  constructor(resource: string, state: string, cause: unknown);
+}
+/** Library errors that can trigger a configured resource `Error` state. */
+type ResourceStateError = ResourceModuleLoadError | ResourceRenderError;
+//#endregion
+export { ResourceModuleLoadError, ResourceRenderError, ResourceStateError };
+//# sourceMappingURL=resource-state-error.d.mts.map

package/dist/errors/resource-state-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-state-error.d.mts","names":[],"sources":["../../src/errors/resource-state-error.ts"],"mappings":";;cACa,uBAAA,SAAgC,KAAK;EAAA,SAIrC,QAAA;EAAA,SAHF,IAAA;cAGE,QAAA,UACT,KAAA;AAAA;;cAQS,mBAAA,SAA4B,KAAK;EAAA,SAIjC,QAAA;EAAA,SACA,KAAA;EAAA,SAJF,IAAA;cAGE,QAAA,UACA,KAAA,UACT,KAAA;AAAA;AANJ;AAAA,KAgBY,kBAAA,GACR,uBAAA,GACA,mBAAmB"}

package/dist/errors/resource-state-error.mjs

@@ -0,0 +1,27 @@
+//#region src/errors/resource-state-error.ts
+/** Identifies a failed dynamic import for a resource layout or render state. */
+var ResourceModuleLoadError = class extends Error {
+	resource;
+	code = "resourceModuleLoad";
+	constructor(resource, cause) {
+		super(`Unable to load resource module "${resource}"`, { cause });
+		this.resource = resource;
+		this.name = "ResourceModuleLoadError";
+	}
+};
+/** Wraps an exception thrown while rendering a named resource state. */
+var ResourceRenderError = class extends Error {
+	resource;
+	state;
+	code = "resourceRender";
+	constructor(resource, state, cause) {
+		super(`Unable to render resource "${resource}" state "${state}"`, { cause });
+		this.resource = resource;
+		this.state = state;
+		this.name = "ResourceRenderError";
+	}
+};
+
+//#endregion
+export { ResourceModuleLoadError, ResourceRenderError };
+//# sourceMappingURL=resource-state-error.mjs.map

package/dist/errors/resource-state-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-state-error.mjs","names":[],"sources":["../../src/errors/resource-state-error.ts"],"sourcesContent":["/** Identifies a failed dynamic import for a resource layout or render state. */\nexport class ResourceModuleLoadError extends Error {\n  readonly code = 'resourceModuleLoad';\n\n  constructor(\n    readonly resource: string,\n    cause: unknown,\n  ) {\n    super(`Unable to load resource module \"${resource}\"`, { cause });\n    this.name = 'ResourceModuleLoadError';\n  }\n}\n\n/** Wraps an exception thrown while rendering a named resource state. */\nexport class ResourceRenderError extends Error {\n  readonly code = 'resourceRender';\n\n  constructor(\n    readonly resource: string,\n    readonly state: string,\n    cause: unknown,\n  ) {\n    super(`Unable to render resource \"${resource}\" state \"${state}\"`, {\n      cause,\n    });\n    this.name = 'ResourceRenderError';\n  }\n}\n\n/** Library errors that can trigger a configured resource `Error` state. */\nexport type ResourceStateError =\n  | ResourceModuleLoadError\n  | ResourceRenderError;\n"],"mappings":";;AACA,IAAa,0BAAb,cAA6C,MAAM;CAItC;CAHX,AAAS,OAAO;CAEhB,YACE,AAAS,UACT,OACA;EACA,MAAM,mCAAmC,SAAS,IAAI,EAAE,MAAM,CAAC;EAHtD;EAIT,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAIlC;CACA;CAJX,AAAS,OAAO;CAEhB,YACE,AAAS,UACT,AAAS,OACT,OACA;EACA,MAAM,8BAA8B,SAAS,WAAW,MAAM,IAAI,EAChE,MACF,CAAC;EANQ;EACA;EAMT,KAAK,OAAO;CACd;AACF"}