@entifix/react-integration 0.1.0-0

package/dist/hooks/use-entity-form/use-entity-form.types.d.ts

@@ -0,0 +1,173 @@
+import type { Entity, EntityConstructor, EntityDraft, EntityDraftValue, EntityLinkSelection, StandardSchemaV1 } from '@entifix/core';
+import type { EntityDraftMessages } from './use-entity-form.helpers.js';
+/**
+ * Where an autosaved draft is persisted, as the form sees it.
+ *
+ * A **port**, because the store cannot be imported: `useDraft` and the zustand
+ * store behind it are `layer:shell`, this package is `layer:entifix`, and
+ * `@nx/enforce-module-boundaries` fails the build on the upward edge. Retagging
+ * to make it legal would put an IndexedDB store under the framework layer, so
+ * the shell implements this instead — `useEntityDraft` in `@entifix/next-shell`
+ * is the one adapter today.
+ *
+ * It lives here rather than in `@entifix/core`, and the asymmetry with
+ * `EntityLinkSource` is deliberate: that port sits in core because
+ * `@entifix/react-controls` and `@entifix/react-integration` are both
+ * `entifix:react` and may not import each other, so they *had* to meet below
+ * both. Nothing forces that here — `@entifix/next-shell` already imports this
+ * hook — so the port stays beside the options it joins.
+ *
+ * Everything it carries is JSON round-trippable, because a draft is written
+ * through `createJSONStorage`
+ * ([ADR 0032](../../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).
+ * `EntityDraft` is that guarantee's compile-time half.
+ */
+export interface EntityDraftStore {
+    /**
+     * The persisted draft, layered over the record's seed — how a workspace
+     * restores an autosaved, half-finished edit.
+     *
+     * It wins on *values*, never on *keys*: a member the entity no longer declares
+     * is dropped and one the draft never held keeps its seeded value, so a draft
+     * written under an older shape cannot leave a field uncontrolled. See
+     * `restoreEntityDraft`.
+     */
+    readonly draft?: EntityDraft;
+    /**
+     * Persist the draft. Called on every edit away from the seed.
+     *
+     * Must be referentially stable across renders: the hook writes from an effect
+     * keyed on it, so a new identity each render turns every render into a write.
+     */
+    save(draft: EntityDraft): void;
+    /**
+     * Discard the persisted draft.
+     *
+     * **The hook never calls this.** A draft is spent when the write *commits*,
+     * and the hook does not know whether it did — it neither fetches nor saves.
+     * The host that owns the mutation calls it on success. Naming it on the port
+     * anyway is what stops each host re-deriving the address it would clear by.
+     */
+    clear(): void;
+}
+export interface UseEntityFormOptions<TEntity extends Entity> {
+    /** Metadata source; fields and their validation rules derive from it. */
+    entityConstructor: EntityConstructor<TEntity>;
+    /**
+     * Copy for the four field-level validation failures. Omit and the keys
+     * render, which is what an adopter with no i18n library sees.
+     */
+    validationMessages?: EntityDraftMessages;
+    /**
+     * Resolves a schema issue's message, which is authored as a catalog key
+     * (`validation.minLength`) so a rule written in one language never reaches a
+     * user untranslated. `useTranslateKey` from the controls package is what a
+     * host passes; omit it and the message renders as authored.
+     */
+    translateKey?: (key: string, params?: Record<string, unknown>) => string;
+    /** The record being edited; seeds the initial draft. Omit to create. */
+    entity?: TEntity;
+    /**
+     * Where to persist this form's draft, so a half-finished edit survives a
+     * refresh. Omit and the form is ephemeral — which is what a plain route wants,
+     * and why autosave is opt-in rather than a flag a host can set wrong.
+     */
+    draft?: EntityDraftStore;
+    /**
+     * Edit only these members, by accessor name. Omit and the form owns them all.
+     *
+     * It narrows the **descriptors**, so it narrows seeding, coercion *and*
+     * validation together — which is the whole point. A wizard splits one entity
+     * across several steps, and without this every step would validate the whole
+     * record: step one could not advance until members it does not show were
+     * filled, and the required-ness of a field would depend on which step you
+     * were standing on.
+     *
+     * The submit therefore receives a **partial** draft. Merging the steps and
+     * rebuilding the entity is the host's job, exactly as it already is for one
+     * form ([ADR 0045](../../../../../../../docs/adr/0045-the-wizard-a-step-graph-and-a-submit-that-hands-off.md)).
+     *
+     * A fresh array literal per render is fine: the memo behind it keys on the
+     * names rather than the array's identity.
+     */
+    fields?: readonly string[];
+    /**
+     * A Standard Schema (Zod, Valibot, ArkType — anything exposing `~standard`)
+     * for the rules metadata cannot express: regex, min/max, cross-field.
+     *
+     * Authored against the **string draft**, so it coerces (`z.coerce.number()`)
+     * rather than expecting typed values. Each message is a catalog key
+     * (`validation.minLength`), resolved against the `controls` namespace with the
+     * literal as its fallback — a rule written in one language would otherwise
+     * reach the user untranslated. An issue with no path becomes `formError`.
+     *
+     * Synchronous rules only: validation runs in a synchronous pass, so an async
+     * schema throws rather than silently passing. Put asynchronous checks — a
+     * uniqueness lookup, say — behind {@link UseEntityFormOptions.validate}.
+     */
+    schema?: StandardSchemaV1;
+    /**
+     * Extra validation beyond the metadata and schema rules, returning a
+     * field-name → message map. Applied last, so it wins on conflict.
+     */
+    validate?: (values: EntityDraft) => Record<string, string>;
+    /** Called with the draft once it passes validation. */
+    onSubmit: (values: EntityDraft) => void | Promise<void>;
+}
+export interface UseEntityFormResult {
+    /** The current draft. Feed straight into `EntityForm`'s `values`. */
+    values: EntityDraft;
+    /** Field-name → message, surfaced only after a submit attempt. */
+    errors: Record<string, string>;
+    /**
+     * The message that belongs to no single field — a cross-field schema rule.
+     * Feed into `EntityForm`'s `formError`, which has nowhere else to show it.
+     */
+    formError?: string;
+    /**
+     * Feed into `EntityForm`'s `onFieldChange`.
+     *
+     * A scalar takes a string; a `composition` takes its list of rows, the one
+     * member with no lossless string form.
+     */
+    setField: (name: string, value: EntityDraftValue) => void;
+    /**
+     * The instances behind the relation ids the draft holds — seeded from the
+     * record's already-materialized links, extended by every pick, and refilled
+     * from a resolved id by {@link UseEntityFormResult.hydrateLink}.
+     *
+     * Pass to `applyEntityLinks` at submit: the draft alone cannot express an
+     * embedded relation, because an id is not an entity. It is not persisted — a
+     * restored draft arrives with ids and no instances, which is what
+     * `hydrateLink` exists to repair.
+     */
+    links: EntityLinkSelection;
+    /**
+     * Feed into `EntityForm`'s `onLinkChange`. Records the picked instance and
+     * writes its id into the draft, which stays the serializable source of truth.
+     */
+    setLink: (name: string, entity: Entity | undefined) => void;
+    /**
+     * Record an instance resolved from an id the draft already held — the restore
+     * path, not a pick.
+     *
+     * Unlike {@link UseEntityFormResult.setLink} it writes only the sidecar, so it
+     * cannot dirty a form the user has not touched. It also never overwrites an
+     * entry that is already there: a pick in flight is newer than a lookup that
+     * started before it.
+     */
+    hydrateLink: (name: string, resolved: Entity) => void;
+    /**
+     * Validate, then submit when clean. Feed into `EntityForm`'s `onSubmit`.
+     *
+     * **Resolves `true` only when the submit actually ran**, so a caller that has
+     * to gate on the outcome — a wizard, whose "Siguiente" *is* the step's submit
+     * — can await it instead of awaiting a tick and re-reading `errors`. A caller
+     * with nothing to gate ignores the promise and is unaffected, which is every
+     * existing one.
+     */
+    submit: () => Promise<boolean>;
+    /** True once any field has been edited away from its seed. */
+    isDirty: boolean;
+}
+//# sourceMappingURL=use-entity-form.types.d.ts.map

package/dist/hooks/use-entity-form/use-entity-form.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-entity-form.types.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-form/use-entity-form.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM;IAC1D,yEAAyE;IACzE,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,mBAAmB,CAAC;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IACzE,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3D,uDAAuD;IACvD,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,MAAM,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC1D;;;;;;;;;OASG;IACH,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAC5D;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/hooks/use-entity-form/use-entity-form.types.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=use-entity-form.types.js.map

package/dist/hooks/use-entity-form/use-entity-form.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-form/use-entity-form.types.ts"],"sourcesContent":["import type {\n  Entity,\n  EntityConstructor,\n  EntityDraft,\n  EntityDraftValue,\n  EntityLinkSelection,\n  StandardSchemaV1,\n} from '@entifix/core';\n\nimport type { EntityDraftMessages } from './use-entity-form.helpers.js';\n\n/**\n * Where an autosaved draft is persisted, as the form sees it.\n *\n * A **port**, because the store cannot be imported: `useDraft` and the zustand\n * store behind it are `layer:shell`, this package is `layer:entifix`, and\n * `@nx/enforce-module-boundaries` fails the build on the upward edge. Retagging\n * to make it legal would put an IndexedDB store under the framework layer, so\n * the shell implements this instead — `useEntityDraft` in `@entifix/next-shell`\n * is the one adapter today.\n *\n * It lives here rather than in `@entifix/core`, and the asymmetry with\n * `EntityLinkSource` is deliberate: that port sits in core because\n * `@entifix/react-controls` and `@entifix/react-integration` are both\n * `entifix:react` and may not import each other, so they *had* to meet below\n * both. Nothing forces that here — `@entifix/next-shell` already imports this\n * hook — so the port stays beside the options it joins.\n *\n * Everything it carries is JSON round-trippable, because a draft is written\n * through `createJSONStorage`\n * ([ADR 0032](../../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).\n * `EntityDraft` is that guarantee's compile-time half.\n */\nexport interface EntityDraftStore {\n  /**\n   * The persisted draft, layered over the record's seed — how a workspace\n   * restores an autosaved, half-finished edit.\n   *\n   * It wins on *values*, never on *keys*: a member the entity no longer declares\n   * is dropped and one the draft never held keeps its seeded value, so a draft\n   * written under an older shape cannot leave a field uncontrolled. See\n   * `restoreEntityDraft`.\n   */\n  readonly draft?: EntityDraft;\n  /**\n   * Persist the draft. Called on every edit away from the seed.\n   *\n   * Must be referentially stable across renders: the hook writes from an effect\n   * keyed on it, so a new identity each render turns every render into a write.\n   */\n  save(draft: EntityDraft): void;\n  /**\n   * Discard the persisted draft.\n   *\n   * **The hook never calls this.** A draft is spent when the write *commits*,\n   * and the hook does not know whether it did — it neither fetches nor saves.\n   * The host that owns the mutation calls it on success. Naming it on the port\n   * anyway is what stops each host re-deriving the address it would clear by.\n   */\n  clear(): void;\n}\n\nexport interface UseEntityFormOptions<TEntity extends Entity> {\n  /** Metadata source; fields and their validation rules derive from it. */\n  entityConstructor: EntityConstructor<TEntity>;\n  /**\n   * Copy for the four field-level validation failures. Omit and the keys\n   * render, which is what an adopter with no i18n library sees.\n   */\n  validationMessages?: EntityDraftMessages;\n  /**\n   * Resolves a schema issue's message, which is authored as a catalog key\n   * (`validation.minLength`) so a rule written in one language never reaches a\n   * user untranslated. `useTranslateKey` from the controls package is what a\n   * host passes; omit it and the message renders as authored.\n   */\n  translateKey?: (key: string, params?: Record<string, unknown>) => string;\n  /** The record being edited; seeds the initial draft. Omit to create. */\n  entity?: TEntity;\n  /**\n   * Where to persist this form's draft, so a half-finished edit survives a\n   * refresh. Omit and the form is ephemeral — which is what a plain route wants,\n   * and why autosave is opt-in rather than a flag a host can set wrong.\n   */\n  draft?: EntityDraftStore;\n  /**\n   * Edit only these members, by accessor name. Omit and the form owns them all.\n   *\n   * It narrows the **descriptors**, so it narrows seeding, coercion *and*\n   * validation together — which is the whole point. A wizard splits one entity\n   * across several steps, and without this every step would validate the whole\n   * record: step one could not advance until members it does not show were\n   * filled, and the required-ness of a field would depend on which step you\n   * were standing on.\n   *\n   * The submit therefore receives a **partial** draft. Merging the steps and\n   * rebuilding the entity is the host's job, exactly as it already is for one\n   * form ([ADR 0045](../../../../../../../docs/adr/0045-the-wizard-a-step-graph-and-a-submit-that-hands-off.md)).\n   *\n   * A fresh array literal per render is fine: the memo behind it keys on the\n   * names rather than the array's identity.\n   */\n  fields?: readonly string[];\n  /**\n   * A Standard Schema (Zod, Valibot, ArkType — anything exposing `~standard`)\n   * for the rules metadata cannot express: regex, min/max, cross-field.\n   *\n   * Authored against the **string draft**, so it coerces (`z.coerce.number()`)\n   * rather than expecting typed values. Each message is a catalog key\n   * (`validation.minLength`), resolved against the `controls` namespace with the\n   * literal as its fallback — a rule written in one language would otherwise\n   * reach the user untranslated. An issue with no path becomes `formError`.\n   *\n   * Synchronous rules only: validation runs in a synchronous pass, so an async\n   * schema throws rather than silently passing. Put asynchronous checks — a\n   * uniqueness lookup, say — behind {@link UseEntityFormOptions.validate}.\n   */\n  schema?: StandardSchemaV1;\n  /**\n   * Extra validation beyond the metadata and schema rules, returning a\n   * field-name → message map. Applied last, so it wins on conflict.\n   */\n  validate?: (values: EntityDraft) => Record<string, string>;\n  /** Called with the draft once it passes validation. */\n  onSubmit: (values: EntityDraft) => void | Promise<void>;\n}\n\nexport interface UseEntityFormResult {\n  /** The current draft. Feed straight into `EntityForm`'s `values`. */\n  values: EntityDraft;\n  /** Field-name → message, surfaced only after a submit attempt. */\n  errors: Record<string, string>;\n  /**\n   * The message that belongs to no single field — a cross-field schema rule.\n   * Feed into `EntityForm`'s `formError`, which has nowhere else to show it.\n   */\n  formError?: string;\n  /**\n   * Feed into `EntityForm`'s `onFieldChange`.\n   *\n   * A scalar takes a string; a `composition` takes its list of rows, the one\n   * member with no lossless string form.\n   */\n  setField: (name: string, value: EntityDraftValue) => void;\n  /**\n   * The instances behind the relation ids the draft holds — seeded from the\n   * record's already-materialized links, extended by every pick, and refilled\n   * from a resolved id by {@link UseEntityFormResult.hydrateLink}.\n   *\n   * Pass to `applyEntityLinks` at submit: the draft alone cannot express an\n   * embedded relation, because an id is not an entity. It is not persisted — a\n   * restored draft arrives with ids and no instances, which is what\n   * `hydrateLink` exists to repair.\n   */\n  links: EntityLinkSelection;\n  /**\n   * Feed into `EntityForm`'s `onLinkChange`. Records the picked instance and\n   * writes its id into the draft, which stays the serializable source of truth.\n   */\n  setLink: (name: string, entity: Entity | undefined) => void;\n  /**\n   * Record an instance resolved from an id the draft already held — the restore\n   * path, not a pick.\n   *\n   * Unlike {@link UseEntityFormResult.setLink} it writes only the sidecar, so it\n   * cannot dirty a form the user has not touched. It also never overwrites an\n   * entry that is already there: a pick in flight is newer than a lookup that\n   * started before it.\n   */\n  hydrateLink: (name: string, resolved: Entity) => void;\n  /**\n   * Validate, then submit when clean. Feed into `EntityForm`'s `onSubmit`.\n   *\n   * **Resolves `true` only when the submit actually ran**, so a caller that has\n   * to gate on the outcome — a wizard, whose \"Siguiente\" *is* the step's submit\n   * — can await it instead of awaiting a tick and re-reading `errors`. A caller\n   * with nothing to gate ignores the promise and is unaffected, which is every\n   * existing one.\n   */\n  submit: () => Promise<boolean>;\n  /** True once any field has been edited away from its seed. */\n  isDirty: boolean;\n}\n"],"names":[],"mappings":"AA+HA,WAuDC"}

package/dist/hooks/use-entity-link-resolver/index.d.ts

@@ -0,0 +1,2 @@
+export * from './use-entity-link-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/use-entity-link-resolver/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-link-resolver/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dist/hooks/use-entity-link-resolver/index.js

@@ -0,0 +1,3 @@
+export * from './use-entity-link-resolver.js';
+
+//# sourceMappingURL=index.js.map

package/dist/hooks/use-entity-link-resolver/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-link-resolver/index.ts"],"sourcesContent":["export * from './use-entity-link-resolver.js';\n"],"names":[],"mappings":"AAAA,cAAc,gCAAgC"}

package/dist/hooks/use-entity-link-resolver/use-entity-link-resolver.d.ts

@@ -0,0 +1,17 @@
+import { type ConfigurationRepositoryTag, createEntityLinkResolver, type EntityLinkRegistration, type EntityLinkResolverTag } from '@entifix/business';
+import type { Context } from 'effect';
+export type { EntityLinkRegistration };
+export { createEntityLinkResolver };
+/**
+ * React hook that memoizes an {@link EntityLinkResolverTag} context built from
+ * the given repository adapters. This is the page-level seam for last-mile
+ * wiring: a caller can register cached or state-backed adapters here without
+ * touching the base adapters or the use-case.
+ *
+ * The assembly itself is `createEntityLinkResolver` in
+ * `@entifix/business` — nothing about it is React, and a server
+ * component needs it without dragging this package's hooks along. Re-exported
+ * here so existing client call sites keep one import.
+ */
+export declare function useEntityLinkResolver(configurationStore: Context.Context<ConfigurationRepositoryTag>, registrations: ReadonlyArray<EntityLinkRegistration>): Context.Context<EntityLinkResolverTag>;
+//# sourceMappingURL=use-entity-link-resolver.d.ts.map

package/dist/hooks/use-entity-link-resolver/use-entity-link-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-entity-link-resolver.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-link-resolver/use-entity-link-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,0BAA0B,EAC/B,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,YAAY,EAAE,sBAAsB,EAAE,CAAC;AACvC,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,kBAAkB,EAAE,OAAO,CAAC,OAAO,CAAC,0BAA0B,CAAC,EAC/D,aAAa,EAAE,aAAa,CAAC,sBAAsB,CAAC,GACnD,OAAO,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAaxC"}

package/dist/hooks/use-entity-link-resolver/use-entity-link-resolver.js

@@ -0,0 +1,26 @@
+import { createEntityLinkResolver } from '@entifix/business';
+import { useMemo } from 'react';
+export { createEntityLinkResolver };
+/**
+ * React hook that memoizes an {@link EntityLinkResolverTag} context built from
+ * the given repository adapters. This is the page-level seam for last-mile
+ * wiring: a caller can register cached or state-backed adapters here without
+ * touching the base adapters or the use-case.
+ *
+ * The assembly itself is `createEntityLinkResolver` in
+ * `@entifix/business` — nothing about it is React, and a server
+ * component needs it without dragging this package's hooks along. Re-exported
+ * here so existing client call sites keep one import.
+ */ export function useEntityLinkResolver(configurationStore, registrations) {
+    // Registrations are a static list per page; key the memo on the registered
+    // constructor names so it stays stable across renders without depending on the
+    // array literal's identity.
+    const registrationKey = registrations.map(([entityConstructor])=>entityConstructor.name).join('|');
+    return useMemo(()=>createEntityLinkResolver(configurationStore, registrations), // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        configurationStore,
+        registrationKey
+    ]);
+}
+
+//# sourceMappingURL=use-entity-link-resolver.js.map

package/dist/hooks/use-entity-link-resolver/use-entity-link-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-link-resolver/use-entity-link-resolver.ts"],"sourcesContent":["import {\n  type ConfigurationRepositoryTag,\n  createEntityLinkResolver,\n  type EntityLinkRegistration,\n  type EntityLinkResolverTag,\n} from '@entifix/business';\nimport type { Context } from 'effect';\nimport { useMemo } from 'react';\n\nexport type { EntityLinkRegistration };\nexport { createEntityLinkResolver };\n\n/**\n * React hook that memoizes an {@link EntityLinkResolverTag} context built from\n * the given repository adapters. This is the page-level seam for last-mile\n * wiring: a caller can register cached or state-backed adapters here without\n * touching the base adapters or the use-case.\n *\n * The assembly itself is `createEntityLinkResolver` in\n * `@entifix/business` — nothing about it is React, and a server\n * component needs it without dragging this package's hooks along. Re-exported\n * here so existing client call sites keep one import.\n */\nexport function useEntityLinkResolver(\n  configurationStore: Context.Context<ConfigurationRepositoryTag>,\n  registrations: ReadonlyArray<EntityLinkRegistration>,\n): Context.Context<EntityLinkResolverTag> {\n  // Registrations are a static list per page; key the memo on the registered\n  // constructor names so it stays stable across renders without depending on the\n  // array literal's identity.\n  const registrationKey = registrations\n    .map(([entityConstructor]) => entityConstructor.name)\n    .join('|');\n\n  return useMemo(\n    () => createEntityLinkResolver(configurationStore, registrations),\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [configurationStore, registrationKey],\n  );\n}\n"],"names":["createEntityLinkResolver","useMemo","useEntityLinkResolver","configurationStore","registrations","registrationKey","map","entityConstructor","name","join"],"mappings":"AAAA,SAEEA,wBAAwB,QAGnB,oBAAoB;AAE3B,SAASC,OAAO,QAAQ,QAAQ;AAGhC,SAASD,wBAAwB,GAAG;AAEpC;;;;;;;;;;CAUC,GACD,OAAO,SAASE,sBACdC,kBAA+D,EAC/DC,aAAoD;IAEpD,2EAA2E;IAC3E,+EAA+E;IAC/E,4BAA4B;IAC5B,MAAMC,kBAAkBD,cACrBE,GAAG,CAAC,CAAC,CAACC,kBAAkB,GAAKA,kBAAkBC,IAAI,EACnDC,IAAI,CAAC;IAER,OAAOR,QACL,IAAMD,yBAAyBG,oBAAoBC,gBACnD,uDAAuD;IACvD;QAACD;QAAoBE;KAAgB;AAEzC"}

package/dist/hooks/use-entity-link-source/index.d.ts

@@ -0,0 +1,3 @@
+export * from './use-entity-link-source.js';
+export * from './use-entity-link-source.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/use-entity-link-source/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-link-source/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC"}

package/dist/hooks/use-entity-link-source/index.js

@@ -0,0 +1,4 @@
+export * from './use-entity-link-source.js';
+export * from './use-entity-link-source.types.js';
+
+//# sourceMappingURL=index.js.map

package/dist/hooks/use-entity-link-source/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-link-source/index.ts"],"sourcesContent":["export * from './use-entity-link-source.js';\nexport * from './use-entity-link-source.types.js';\n"],"names":[],"mappings":"AAAA,cAAc,8BAA8B;AAC5C,cAAc,oCAAoC"}

package/dist/hooks/use-entity-link-source/use-entity-link-source.d.ts

@@ -0,0 +1,25 @@
+import { type Entity, type EntityLinkSource } from '@entifix/core';
+import type { EntityLinkSourceConfig, UseEntityLinkSourceOptions } from './use-entity-link-source.types.js';
+/**
+ * Produces the {@link EntityLinkSource} a link editor runs on: the quick
+ * type-ahead, the browse list, and the label of whatever key is currently held.
+ *
+ * This is the data half of the link mechanism. It exists as a hook — rather than
+ * inside the input — because `@entifix/react-controls` may not import this package
+ * (both are `entifix:react`, and the boundary rule forbids the sideways edge), so
+ * the two meet at the framework-free port declared in `@entifix/core`. A form
+ * wrapper calls it once per relation and hands the results to `EntityForm`'s
+ * `linkSources`.
+ *
+ * What may be picked is never decided here: the caller's `loadUc` (and optional
+ * `baseFiltering`) is what restricts the set, so a domain rule about assignable
+ * targets lives in a use-case, not in the UI.
+ *
+ * Three requests, each held back until it means something: the quick search runs
+ * a small page and re-runs on a debounced term; the browse list does not fetch at
+ * all until the dialog opens; and the label is only looked up when the caller has
+ * an id but no instance — a draft restored from storage — because a picked target
+ * already knows its own name.
+ */
+export declare function useEntityLinkSource<TTarget extends Entity, TContext>(config: EntityLinkSourceConfig<TTarget, TContext>, { descriptor, selectedId, selectedEntity, }: UseEntityLinkSourceOptions<TTarget>): EntityLinkSource<TTarget>;
+//# sourceMappingURL=use-entity-link-source.d.ts.map

package/dist/hooks/use-entity-link-source/use-entity-link-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-entity-link-source.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-link-source/use-entity-link-source.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,gBAAgB,EAGtB,MAAM,eAAe,CAAC;AAWvB,OAAO,KAAK,EACV,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,mCAAmC,CAAC;AAgC3C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,MAAM,EAAE,QAAQ,EAClE,MAAM,EAAE,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,EACjD,EACE,UAAU,EACV,UAAU,EACV,cAAc,GACf,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACrC,gBAAgB,CAAC,OAAO,CAAC,CAuJ3B"}

package/dist/hooks/use-entity-link-source/use-entity-link-source.js

@@ -0,0 +1,169 @@
+'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { EntityIdTag, EntityLoadRequestTag } from '@entifix/business';
+import { describeEntityColumns, EntifixLogicError } from '@entifix/core';
+import { useQuery } from '@tanstack/react-query';
+import { Context, Effect } from 'effect';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { combineFilterGroups } from '../../query/combine-filtering.js';
+import { entityQueryKey, entityQueryScope } from '../../query/entity-query-key.js';
+import { useDataLoading } from '../use-data-loading/index.js';
+const DEFAULT_QUICK_PAGE_SIZE = 10;
+const DEFAULT_DEBOUNCE_MS = 250;
+/**
+ * Fails loudly on a search property the service will reject.
+ *
+ * A member's `filterable` metadata is also the server-side filter allowlist, so a
+ * quick search over a member that lacks it answers `400` — as an empty
+ * suggestion list, which reads to the user as "there are no brands". Better to
+ * break the developer's build than to lie to them.
+ */ function assertSearchable(config, searchProperty) {
+    const target = describeEntityColumns(config.entityConstructor).find((column)=>column.name === searchProperty);
+    if ((target == null ? void 0 : target.filterable) === true) return;
+    throw new EntifixLogicError(`Cannot search ${config.entityConstructor.name} by "${searchProperty}": ` + 'the member is not filterable, so the service would reject the query. ' + 'Declare it `filterable` on the target entity, or point the relation at ' + 'another member with `linkSearchProperty`.', undefined, {
+        entity: config.entityConstructor.name,
+        searchProperty
+    });
+}
+/**
+ * Produces the {@link EntityLinkSource} a link editor runs on: the quick
+ * type-ahead, the browse list, and the label of whatever key is currently held.
+ *
+ * This is the data half of the link mechanism. It exists as a hook — rather than
+ * inside the input — because `@entifix/react-controls` may not import this package
+ * (both are `entifix:react`, and the boundary rule forbids the sideways edge), so
+ * the two meet at the framework-free port declared in `@entifix/core`. A form
+ * wrapper calls it once per relation and hands the results to `EntityForm`'s
+ * `linkSources`.
+ *
+ * What may be picked is never decided here: the caller's `loadUc` (and optional
+ * `baseFiltering`) is what restricts the set, so a domain rule about assignable
+ * targets lives in a use-case, not in the UI.
+ *
+ * Three requests, each held back until it means something: the quick search runs
+ * a small page and re-runs on a debounced term; the browse list does not fetch at
+ * all until the dialog opens; and the label is only looked up when the caller has
+ * an id but no instance — a draft restored from storage — because a picked target
+ * already knows its own name.
+ */ export function useEntityLinkSource(config, { descriptor, selectedId, selectedEntity }) {
+    var _ref, _quickQuery_error;
+    var _quickQuery_data;
+    const { entityConstructor, loadUc, getUc, ctx, baseFiltering, quickPageSize = DEFAULT_QUICK_PAGE_SIZE, debounceMs = DEFAULT_DEBOUNCE_MS } = config;
+    const searchProperty = descriptor.linkSearchProperty;
+    assertSearchable(config, searchProperty);
+    // Callers rebuild `loadUc`/`getUc`/`ctx` inline on every render, so the latest
+    // are held in refs and kept out of the query keys — keying on their identity
+    // would refetch on every render. Same reason and same shape as `useDataLoading`.
+    const effects = useRef({
+        loadUc,
+        getUc,
+        ctx
+    });
+    useEffect(()=>{
+        effects.current = {
+            loadUc,
+            getUc,
+            ctx
+        };
+    });
+    const [term, setTerm] = useState('');
+    const [debouncedTerm, setDebouncedTerm] = useState('');
+    const [isOpen, setOpen] = useState(false);
+    // Typing is not a request per keystroke: the term settles first, and only the
+    // settled value reaches the service.
+    useEffect(()=>{
+        const timer = setTimeout(()=>setDebouncedTerm(term), debounceMs);
+        return ()=>clearTimeout(timer);
+    }, [
+        term,
+        debounceMs
+    ]);
+    const quickRequest = useMemo(()=>{
+        const filtering = combineFilterGroups(baseFiltering, debouncedTerm === '' ? undefined : {
+            operator: 'and',
+            values: [
+                {
+                    property: searchProperty,
+                    operator: 'like',
+                    value: debouncedTerm
+                }
+            ]
+        });
+        const request = {
+            page: 1,
+            pageSize: quickPageSize
+        };
+        if (filtering) request.filtering = [
+            filtering
+        ];
+        return request;
+    }, [
+        baseFiltering,
+        debouncedTerm,
+        quickPageSize,
+        searchProperty
+    ]);
+    const quickQuery = useQuery({
+        queryKey: [
+            ...entityQueryKey(entityConstructor, quickRequest),
+            'link-quick'
+        ],
+        queryFn: ()=>Effect.runPromise(Effect.provide(effects.current.loadUc, effects.current.ctx.pipe(Context.add(EntityLoadRequestTag, // The tag carries no generic, so the entity-typed request crosses
+            // it — the same cast `loadUCFactory` makes reading it back.
+            quickRequest))))
+    });
+    const browse = useDataLoading({
+        uc: loadUc,
+        ctx,
+        queryKey: entityQueryScope(entityConstructor),
+        baseFiltering,
+        enabled: isOpen
+    });
+    const needsLabel = selectedEntity === undefined && selectedId != null && getUc !== undefined;
+    const labelQuery = useQuery({
+        queryKey: [
+            ...entityQueryScope(entityConstructor),
+            'link-label',
+            String(selectedId)
+        ],
+        enabled: needsLabel,
+        queryFn: ()=>Effect.runPromise(Effect.provide(// Guarded by `enabled`: the query only runs when both are present.
+            effects.current.getUc, effects.current.ctx.pipe(Context.add(EntityIdTag, selectedId))))
+    });
+    // A blank label is as useless as a missing one, so both fall back to the key —
+    // an unnamed row must still be distinguishable from the row above it.
+    const labelOf = useCallback((target)=>{
+        var _target_id;
+        const label = target[descriptor.linkLabelProperty];
+        return label == null || label === '' ? String((_target_id = target.id) != null ? _target_id : '') : String(label);
+    }, [
+        descriptor.linkLabelProperty
+    ]);
+    const resolved = selectedEntity != null ? selectedEntity : labelQuery.data;
+    return {
+        entityConstructor,
+        labelOf,
+        selected: {
+            label: resolved === undefined ? undefined : labelOf(resolved),
+            // The whole target, not only its name. The lookup above already fetched
+            // it, and a form restoring a draft has nothing else to rebuild an
+            // `embedded` relation from — the draft kept the id and lost the instance.
+            entity: resolved,
+            isLoading: needsLabel && labelQuery.isFetching
+        },
+        quick: {
+            term,
+            setTerm,
+            options: (_ref = (_quickQuery_data = quickQuery.data) == null ? void 0 : _quickQuery_data.items) != null ? _ref : [],
+            isLoading: quickQuery.isFetching,
+            error: (_quickQuery_error = quickQuery.error) != null ? _quickQuery_error : undefined
+        },
+        browse: _extends({}, browse, {
+            isOpen,
+            open: ()=>setOpen(true),
+            close: ()=>setOpen(false)
+        })
+    };
+}
+
+//# sourceMappingURL=use-entity-link-source.js.map

package/dist/hooks/use-entity-link-source/use-entity-link-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-link-source/use-entity-link-source.ts"],"sourcesContent":["'use client';\n\nimport { EntityIdTag, EntityLoadRequestTag } from '@entifix/business';\nimport {\n  describeEntityColumns,\n  type EntifixError,\n  EntifixLogicError,\n  type Entity,\n  type EntityLinkSource,\n  type EntityLoadRequest,\n  type EntityPage,\n} from '@entifix/core';\nimport { useQuery } from '@tanstack/react-query';\nimport { Context, Effect } from 'effect';\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\n\nimport { combineFilterGroups } from '../../query/combine-filtering.js';\nimport {\n  entityQueryKey,\n  entityQueryScope,\n} from '../../query/entity-query-key.js';\nimport { useDataLoading } from '../use-data-loading/index.js';\nimport type {\n  EntityLinkSourceConfig,\n  UseEntityLinkSourceOptions,\n} from './use-entity-link-source.types.js';\n\nconst DEFAULT_QUICK_PAGE_SIZE = 10;\nconst DEFAULT_DEBOUNCE_MS = 250;\n\n/**\n * Fails loudly on a search property the service will reject.\n *\n * A member's `filterable` metadata is also the server-side filter allowlist, so a\n * quick search over a member that lacks it answers `400` — as an empty\n * suggestion list, which reads to the user as \"there are no brands\". Better to\n * break the developer's build than to lie to them.\n */\nfunction assertSearchable<TTarget extends Entity>(\n  config: EntityLinkSourceConfig<TTarget, unknown>,\n  searchProperty: string,\n): void {\n  const target = describeEntityColumns(config.entityConstructor).find(\n    column => column.name === searchProperty,\n  );\n  if (target?.filterable === true) return;\n\n  throw new EntifixLogicError(\n    `Cannot search ${config.entityConstructor.name} by \"${searchProperty}\": ` +\n      'the member is not filterable, so the service would reject the query. ' +\n      'Declare it `filterable` on the target entity, or point the relation at ' +\n      'another member with `linkSearchProperty`.',\n    undefined,\n    { entity: config.entityConstructor.name, searchProperty },\n  );\n}\n\n/**\n * Produces the {@link EntityLinkSource} a link editor runs on: the quick\n * type-ahead, the browse list, and the label of whatever key is currently held.\n *\n * This is the data half of the link mechanism. It exists as a hook — rather than\n * inside the input — because `@entifix/react-controls` may not import this package\n * (both are `entifix:react`, and the boundary rule forbids the sideways edge), so\n * the two meet at the framework-free port declared in `@entifix/core`. A form\n * wrapper calls it once per relation and hands the results to `EntityForm`'s\n * `linkSources`.\n *\n * What may be picked is never decided here: the caller's `loadUc` (and optional\n * `baseFiltering`) is what restricts the set, so a domain rule about assignable\n * targets lives in a use-case, not in the UI.\n *\n * Three requests, each held back until it means something: the quick search runs\n * a small page and re-runs on a debounced term; the browse list does not fetch at\n * all until the dialog opens; and the label is only looked up when the caller has\n * an id but no instance — a draft restored from storage — because a picked target\n * already knows its own name.\n */\nexport function useEntityLinkSource<TTarget extends Entity, TContext>(\n  config: EntityLinkSourceConfig<TTarget, TContext>,\n  {\n    descriptor,\n    selectedId,\n    selectedEntity,\n  }: UseEntityLinkSourceOptions<TTarget>,\n): EntityLinkSource<TTarget> {\n  const {\n    entityConstructor,\n    loadUc,\n    getUc,\n    ctx,\n    baseFiltering,\n    quickPageSize = DEFAULT_QUICK_PAGE_SIZE,\n    debounceMs = DEFAULT_DEBOUNCE_MS,\n  } = config;\n\n  const searchProperty = descriptor.linkSearchProperty;\n  assertSearchable(\n    config as unknown as EntityLinkSourceConfig<TTarget, unknown>,\n    searchProperty,\n  );\n\n  // Callers rebuild `loadUc`/`getUc`/`ctx` inline on every render, so the latest\n  // are held in refs and kept out of the query keys — keying on their identity\n  // would refetch on every render. Same reason and same shape as `useDataLoading`.\n  const effects = useRef({ loadUc, getUc, ctx });\n  useEffect(() => {\n    effects.current = { loadUc, getUc, ctx };\n  });\n\n  const [term, setTerm] = useState('');\n  const [debouncedTerm, setDebouncedTerm] = useState('');\n  const [isOpen, setOpen] = useState(false);\n\n  // Typing is not a request per keystroke: the term settles first, and only the\n  // settled value reaches the service.\n  useEffect(() => {\n    const timer = setTimeout(() => setDebouncedTerm(term), debounceMs);\n    return () => clearTimeout(timer);\n  }, [term, debounceMs]);\n\n  const quickRequest = useMemo<EntityLoadRequest<TTarget>>(() => {\n    const filtering = combineFilterGroups<TTarget>(\n      baseFiltering,\n      debouncedTerm === ''\n        ? undefined\n        : {\n            operator: 'and',\n            values: [\n              {\n                property: searchProperty as keyof TTarget,\n                operator: 'like',\n                value: debouncedTerm,\n              },\n            ],\n          },\n    );\n\n    const request: EntityLoadRequest<TTarget> = {\n      page: 1,\n      pageSize: quickPageSize,\n    };\n    if (filtering) request.filtering = [filtering];\n    return request;\n  }, [baseFiltering, debouncedTerm, quickPageSize, searchProperty]);\n\n  const quickQuery = useQuery<EntityPage<TTarget>, EntifixError>({\n    queryKey: [\n      ...entityQueryKey(entityConstructor, quickRequest),\n      'link-quick',\n    ],\n    queryFn: () =>\n      Effect.runPromise(\n        Effect.provide(\n          effects.current.loadUc,\n          effects.current.ctx.pipe(\n            Context.add(\n              EntityLoadRequestTag,\n              // The tag carries no generic, so the entity-typed request crosses\n              // it — the same cast `loadUCFactory` makes reading it back.\n              quickRequest as unknown as EntityLoadRequest,\n            ),\n          ),\n        ),\n      ),\n  });\n\n  const browse = useDataLoading<TTarget, TContext>({\n    uc: loadUc,\n    ctx,\n    queryKey: entityQueryScope(entityConstructor),\n    baseFiltering,\n    enabled: isOpen,\n  });\n\n  const needsLabel =\n    selectedEntity === undefined && selectedId != null && getUc !== undefined;\n\n  const labelQuery = useQuery<TTarget, EntifixError>({\n    queryKey: [\n      ...entityQueryScope(entityConstructor),\n      'link-label',\n      String(selectedId),\n    ],\n    enabled: needsLabel,\n    queryFn: () =>\n      Effect.runPromise(\n        Effect.provide(\n          // Guarded by `enabled`: the query only runs when both are present.\n          effects.current.getUc as NonNullable<typeof getUc>,\n          effects.current.ctx.pipe(Context.add(EntityIdTag, selectedId)),\n        ),\n      ),\n  });\n\n  // A blank label is as useless as a missing one, so both fall back to the key —\n  // an unnamed row must still be distinguishable from the row above it.\n  const labelOf = useCallback(\n    (target: TTarget) => {\n      const label = (target as Record<string, unknown>)[\n        descriptor.linkLabelProperty\n      ];\n      return label == null || label === ''\n        ? String(target.id ?? '')\n        : String(label);\n    },\n    [descriptor.linkLabelProperty],\n  );\n\n  const resolved = selectedEntity ?? labelQuery.data;\n\n  return {\n    entityConstructor,\n    labelOf,\n    selected: {\n      label: resolved === undefined ? undefined : labelOf(resolved),\n      // The whole target, not only its name. The lookup above already fetched\n      // it, and a form restoring a draft has nothing else to rebuild an\n      // `embedded` relation from — the draft kept the id and lost the instance.\n      entity: resolved,\n      isLoading: needsLabel && labelQuery.isFetching,\n    },\n    quick: {\n      term,\n      setTerm,\n      options: quickQuery.data?.items ?? [],\n      isLoading: quickQuery.isFetching,\n      error: quickQuery.error ?? undefined,\n    },\n    browse: {\n      ...browse,\n      isOpen,\n      open: () => setOpen(true),\n      close: () => setOpen(false),\n    },\n  };\n}\n"],"names":["EntityIdTag","EntityLoadRequestTag","describeEntityColumns","EntifixLogicError","useQuery","Context","Effect","useCallback","useEffect","useMemo","useRef","useState","combineFilterGroups","entityQueryKey","entityQueryScope","useDataLoading","DEFAULT_QUICK_PAGE_SIZE","DEFAULT_DEBOUNCE_MS","assertSearchable","config","searchProperty","target","entityConstructor","find","column","name","filterable","undefined","entity","useEntityLinkSource","descriptor","selectedId","selectedEntity","quickQuery","loadUc","getUc","ctx","baseFiltering","quickPageSize","debounceMs","linkSearchProperty","effects","current","term","setTerm","debouncedTerm","setDebouncedTerm","isOpen","setOpen","timer","setTimeout","clearTimeout","quickRequest","filtering","operator","values","property","value","request","page","pageSize","queryKey","queryFn","runPromise","provide","pipe","add","browse","uc","enabled","needsLabel","labelQuery","String","labelOf","label","linkLabelProperty","id","resolved","data","selected","isLoading","isFetching","quick","options","items","error","open","close"],"mappings":"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"}

package/dist/hooks/use-entity-link-source/use-entity-link-source.types.d.ts

@@ -0,0 +1,49 @@
+import type { EntityIdTag, EntityLoadRequestTag } from '@entifix/business';
+import type { EntifixError, Entity, EntityConstructor, EntityFieldDescriptor, EntityId, EntityPage, FilterGroup } from '@entifix/core';
+import type { Context, Effect } from 'effect';
+/**
+ * Where a picker's targets come from, and what may be picked.
+ *
+ * The use-cases are the parametrization seam: a domain that must restrict what is
+ * assignable supplies its own list use-case (only active brands, only leaf
+ * categories) instead of the generic `loadUCFactory`, and the picker never learns
+ * the rule. {@link baseFiltering} is the lighter version of the same idea for a
+ * restriction that needs no use-case of its own.
+ */
+export interface EntityLinkSourceConfig<TTarget extends Entity, TContext> {
+    entityConstructor: EntityConstructor<TTarget>;
+    /** Lists the targets. Supplies {@link EntityLoadRequestTag} per request. */
+    loadUc: Effect.Effect<EntityPage<TTarget>, EntifixError, EntityLoadRequestTag | TContext>;
+    /**
+     * Loads one target by id — how a draft restored from storage turns its held
+     * foreign key back into a name. Omit it and the input falls back to showing
+     * the bare key.
+     */
+    getUc?: Effect.Effect<TTarget, EntifixError, EntityIdTag | TContext>;
+    ctx: Context.Context<TContext>;
+    /**
+     * ANDed into every quick and browse request, so a caller can narrow the
+     * selectable set without writing a use-case.
+     */
+    baseFiltering?: FilterGroup<TTarget>;
+    /** How many suggestions the quick search asks for. Defaults to 10. */
+    quickPageSize?: number;
+    /** Milliseconds of quiet before a typed term is sent. Defaults to 250. */
+    debounceMs?: number;
+}
+export interface UseEntityLinkSourceOptions<TTarget extends Entity> {
+    /**
+     * The relation being edited. Its `linkSearchProperty` is what the quick search
+     * filters on and its `linkLabelProperty` is what a target reads as.
+     */
+    descriptor: EntityFieldDescriptor;
+    /** The foreign key the draft currently holds. */
+    selectedId?: EntityId;
+    /**
+     * The instance behind {@link selectedId} when the caller already has it — the
+     * one the user just picked, or the one a loaded record carried. Present, it
+     * spares the label request entirely.
+     */
+    selectedEntity?: TTarget;
+}
+//# sourceMappingURL=use-entity-link-source.types.d.ts.map

package/dist/hooks/use-entity-link-source/use-entity-link-source.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-entity-link-source.types.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-link-source/use-entity-link-source.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,iBAAiB,EACjB,qBAAqB,EACrB,QAAQ,EACR,UAAU,EACV,WAAW,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,MAAM,EAAE,QAAQ;IACtE,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,CACnB,UAAU,CAAC,OAAO,CAAC,EACnB,YAAY,EACZ,oBAAoB,GAAG,QAAQ,CAChC,CAAC;IACF;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;IACrE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,MAAM;IAChE;;;OAGG;IACH,UAAU,EAAE,qBAAqB,CAAC;IAClC,iDAAiD;IACjD,UAAU,CAAC,EAAE,QAAQ,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/dist/hooks/use-entity-link-source/use-entity-link-source.types.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=use-entity-link-source.types.js.map

package/dist/hooks/use-entity-link-source/use-entity-link-source.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-link-source/use-entity-link-source.types.ts"],"sourcesContent":["import type { EntityIdTag, EntityLoadRequestTag } from '@entifix/business';\nimport type {\n  EntifixError,\n  Entity,\n  EntityConstructor,\n  EntityFieldDescriptor,\n  EntityId,\n  EntityPage,\n  FilterGroup,\n} from '@entifix/core';\nimport type { Context, Effect } from 'effect';\n\n/**\n * Where a picker's targets come from, and what may be picked.\n *\n * The use-cases are the parametrization seam: a domain that must restrict what is\n * assignable supplies its own list use-case (only active brands, only leaf\n * categories) instead of the generic `loadUCFactory`, and the picker never learns\n * the rule. {@link baseFiltering} is the lighter version of the same idea for a\n * restriction that needs no use-case of its own.\n */\nexport interface EntityLinkSourceConfig<TTarget extends Entity, TContext> {\n  entityConstructor: EntityConstructor<TTarget>;\n  /** Lists the targets. Supplies {@link EntityLoadRequestTag} per request. */\n  loadUc: Effect.Effect<\n    EntityPage<TTarget>,\n    EntifixError,\n    EntityLoadRequestTag | TContext\n  >;\n  /**\n   * Loads one target by id — how a draft restored from storage turns its held\n   * foreign key back into a name. Omit it and the input falls back to showing\n   * the bare key.\n   */\n  getUc?: Effect.Effect<TTarget, EntifixError, EntityIdTag | TContext>;\n  ctx: Context.Context<TContext>;\n  /**\n   * ANDed into every quick and browse request, so a caller can narrow the\n   * selectable set without writing a use-case.\n   */\n  baseFiltering?: FilterGroup<TTarget>;\n  /** How many suggestions the quick search asks for. Defaults to 10. */\n  quickPageSize?: number;\n  /** Milliseconds of quiet before a typed term is sent. Defaults to 250. */\n  debounceMs?: number;\n}\n\nexport interface UseEntityLinkSourceOptions<TTarget extends Entity> {\n  /**\n   * The relation being edited. Its `linkSearchProperty` is what the quick search\n   * filters on and its `linkLabelProperty` is what a target reads as.\n   */\n  descriptor: EntityFieldDescriptor;\n  /** The foreign key the draft currently holds. */\n  selectedId?: EntityId;\n  /**\n   * The instance behind {@link selectedId} when the caller already has it — the\n   * one the user just picked, or the one a loaded record carried. Present, it\n   * spares the label request entirely.\n   */\n  selectedEntity?: TTarget;\n}\n"],"names":[],"mappings":"AA+CA,WAcC"}

package/dist/hooks/use-entity-mutation/index.d.ts

@@ -0,0 +1,3 @@
+export * from './use-entity-mutation.js';
+export * from './use-entity-mutation.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/use-entity-mutation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/use-entity-mutation/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC"}

package/dist/hooks/use-entity-mutation/index.js

@@ -0,0 +1,4 @@
+export * from './use-entity-mutation.js';
+export * from './use-entity-mutation.types.js';
+
+//# sourceMappingURL=index.js.map

package/dist/hooks/use-entity-mutation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/hooks/use-entity-mutation/index.ts"],"sourcesContent":["export * from './use-entity-mutation.js';\nexport * from './use-entity-mutation.types.js';\n"],"names":[],"mappings":"AAAA,cAAc,2BAA2B;AACzC,cAAc,iCAAiC"}