@domainkit/react 0.10.0 → 0.11.0

package/README.md

@@ -58,12 +58,33 @@ trigger, and the dialog behind that trigger is narrowed to that provider, with t
 disclosure.
 
 When no registered provider serves the zone there is nothing DomainKit can connect, so the flow
-offers nothing. Pass `connect="always"` to offer the all-providers dialog anyway:
+offers nothing. Pass `connect="always"` to offer the all-providers dialog anyway, or `connect="never"`
+for a domain your application has already settled another way. A domain DomainKit holds keeps its
+status and its disconnect whatever the invitation says.
 
 ```tsx
 <Domain.Flow domain="app.example.com" requirements={requirements} connect="always" />
 ```
 
+Connecting is the customer saying yes to the records, so the plan opens itself the moment a
+connection lands — after a token connect, and after the customer returns from a provider — and one
+action adds them. `review="manual"` waits for the trigger instead.
+
+`onState` reports what DomainKit has to say about the domain, so your own offers can be ordered
+beside it rather than competing with it:
+
+```tsx
+<Domain.Flow
+  domain="app.example.com"
+  requirements={requirements}
+  onState={({ connected, offering, provider }) => setDomainKitOffers(connected || offering)}
+/>
+```
+
+Letting a provider go is one dialog: `Disconnect` asks whether to remove the records an apply
+receipt proves DomainKit created, removes them when the option stays checked, then releases the
+connection. `Cleanup.Flow` is still exported for a host that wants removal on its own.
+
 ## Own one piece, keep the rest
 
 Every part of the flow is a slot with a default.
@@ -84,7 +105,7 @@ Every part of the flow is a slot with a default.
 | `connection`   | `{ controller, domain, connect }`               | `Connect.Card` once connected, `Connect.Prompt` until then |
 | `records`      | `{ records, readiness, controller, domain }`    | `Records.Table`                                            |
 | `verification` | `{ controller, domain }`                        | `Verify.Status` with per-requirement evidence              |
-| `actions`      | `{ connection, provisioning, cleanup, domain }` | Review changes, Approve, Decline, Remove records           |
+| `actions`      | `{ connection, provisioning, cleanup, domain }` | Review changes, Approve, Decline                           |
 
 `Domain.Flow` adds no layout container around a slot: its output is a direct child of the flow root,
 so your own grid can place it without `display: contents`.

package/dist/index.d.mts

@@ -553,8 +553,8 @@ interface TitleProps extends PartProps<"div", State$2> {}
 /** The heading from the catalog. Children win, for a host that words it itself. */
 declare function Title(props: TitleProps): ReactElement;
 interface DescriptionProps extends PartProps<"p", State$2> {}
-/** What to do about it, from the catalog. */
-declare function Description(props: DescriptionProps): ReactElement;
+/** What to do about it, from the catalog. An outcome whose title says everything renders none. */
+declare function Description(props: DescriptionProps): ReactElement | null;
 interface ContentProps extends PartProps<"div", State$2> {}
 /**
  * The actions under the header. Without children it is the flow's retry, and a flow that allows
@@ -642,7 +642,7 @@ interface MarkProps extends PartProps<"span", MarkState> {
  */
 declare function Mark({ provider, ...props }: MarkProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 declare namespace connect_d_exports {
-  export { Attempt, Candidate, Card$1 as Card, CardProps$1 as CardProps, ConnectInput, Controller$1 as Controller, Descriptor, Dialog$1 as Dialog, DialogProps$1 as DialogProps, Discovery, Field, Flow$2 as Flow, FlowProps$2 as FlowProps, Form, FormProps, Invitation, MethodDescriptor, Options$2 as Options, Outcome$3 as Outcome, OutcomeProps$2 as OutcomeProps, Prompt, PromptProps, Root$5 as Root, RootProps$5 as RootProps, RootState$3 as RootState, Snapshot, State$1 as State, Status$3 as Status, StatusProps$3 as StatusProps, answeredInPlace, hostProvider, useController$2 as useController };
+  export { Attempt, Candidate, Card$1 as Card, CardProps$1 as CardProps, ConnectInput, Controller$1 as Controller, Descriptor, Dialog$1 as Dialog, DialogProps$1 as DialogProps, DisconnectDialog, DisconnectDialogProps, Discovery, Field, Flow$2 as Flow, FlowProps$2 as FlowProps, Form, FormProps, Invitation, MethodDescriptor, Options$2 as Options, Outcome$3 as Outcome, OutcomeProps$2 as OutcomeProps, Prompt, PromptProps, Root$5 as Root, RootProps$5 as RootProps, RootState$3 as RootState, Snapshot, State$1 as State, Status$3 as Status, StatusProps$3 as StatusProps, answeredInPlace, holdsConnection, hostProvider, offering, useController$2 as useController };
 }
 type Snapshot = Transport.Snapshot;
 type Discovery = Transport.Discovery;
@@ -671,6 +671,7 @@ type State$1 = Data.TaggedEnum<{
   };
   Submitting: {
     readonly snapshot: Snapshot | null;
+    readonly discovery: Discovery | null;
   };
   Redirecting: {
     readonly url: string;
@@ -733,6 +734,7 @@ declare const State$1: {
   }> | Extract<{
     readonly _tag: "Submitting";
     readonly snapshot: Snapshot | null;
+    readonly discovery: Discovery | null;
   }, {
     readonly _tag: Tag;
   }>;
@@ -767,6 +769,7 @@ declare const State$1: {
     } | {
       readonly _tag: "Submitting";
       readonly snapshot: Snapshot | null;
+      readonly discovery: Discovery | null;
     }, {
       readonly _tag: Tag;
     }>) => any; }>(cases: Cases): (value: {
@@ -799,6 +802,7 @@ declare const State$1: {
     } | {
       readonly _tag: "Submitting";
       readonly snapshot: Snapshot | null;
+      readonly discovery: Discovery | null;
     }) => import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Disconnected" | "Failure" | "Loading" | "Reconnect" | "Redirecting" | "SelectionRequired" | "Submitting"]>>;
     <Cases extends { readonly [Tag in "Connected" | "Disconnected" | "Failure" | "Loading" | "Reconnect" | "Redirecting" | "SelectionRequired" | "Submitting"]: (args: Extract<{
       readonly _tag: "Connected";
@@ -830,6 +834,7 @@ declare const State$1: {
     } | {
       readonly _tag: "Submitting";
       readonly snapshot: Snapshot | null;
+      readonly discovery: Discovery | null;
     }, {
       readonly _tag: Tag;
     }>) => any; }>(value: {
@@ -862,6 +867,7 @@ declare const State$1: {
     } | {
       readonly _tag: "Submitting";
       readonly snapshot: Snapshot | null;
+      readonly discovery: Discovery | null;
     }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Disconnected" | "Failure" | "Loading" | "Reconnect" | "Redirecting" | "SelectionRequired" | "Submitting"]>>;
   };
   readonly Connected: Data.TaggedEnum.ConstructorFrom<{
@@ -901,6 +907,7 @@ declare const State$1: {
   readonly Submitting: Data.TaggedEnum.ConstructorFrom<{
     readonly _tag: "Submitting";
     readonly snapshot: Snapshot | null;
+    readonly discovery: Discovery | null;
   }, "_tag">;
 };
 /** Which provider and method the failed command was for, so the form can answer beside it. */
@@ -917,6 +924,13 @@ interface ConnectInput {
   readonly returnTo?: string;
 }
 interface Controller$1 {
+  readonly domain: string;
+  /**
+   * How many times a connection has been established for this domain on this surface: a token
+   * connect that landed, or a load that followed this library's own redirect back. It only ever
+   * grows, so a flow acts on a change rather than on a state that would fire again every render.
+   */
+  readonly established: number;
   readonly state: State$1;
   readonly snapshot: Snapshot | null;
   readonly discovery: Discovery | null;
@@ -962,6 +976,12 @@ declare function Root$5({ controller, ...props }: RootProps$5): ReactElement;
  * A flow rendering its own `Outcome` beside the dialog skips it, so the failure announces once.
  */
 declare const answeredInPlace: (controller: Controller$1) => boolean;
+/**
+ * Whether the surface should read as connected: it is, or a command it started is in flight over a
+ * connection that was. The card and the dialog it opened stay on screen for the length of the
+ * command rather than vanishing under the customer half way through it.
+ */
+declare const holdsConnection: (controller: Controller$1) => boolean;
 /**
  * The provider whose nameservers serve this domain, as the snapshot describes it. Discovery names
  * it by id; without a descriptor there is nothing to draw, so there is no host.
@@ -981,12 +1001,17 @@ interface StatusProps$3 extends PartProps<"p", RootState$3> {
 declare function Status$3({ controller, ...props }: StatusProps$3): ReactElement;
 interface FormProps extends PartProps<"div", RootState$3> {
   readonly controller: Controller$1;
+  /**
+   * Narrow to this provider whatever discovery found. The dialog's header menu sets it, so a
+   * customer who picks another provider gets the same one-decision surface for it.
+   */
+  readonly provider?: string;
 }
 /**
  * Everything a disconnected domain can do: a connection discovery already found, the connections
  * this owner already has, then each provider's declared methods.
  */
-declare function Form({ controller, ...props }: FormProps): ReactElement;
+declare function Form({ controller, provider: narrowed, ...props }: FormProps): ReactElement;
 interface DialogProps$1 {
   readonly controller: Controller$1;
   readonly children?: ReactNode;
@@ -1000,13 +1025,26 @@ interface DialogProps$1 {
 }
 /** The connect surface. Without `render` it is a Base UI dialog behind `trigger`. */
 declare function Dialog$1({ children, controller, render, title, trigger }: DialogProps$1): ReactElement;
-/** Whether the flow offers a connect surface when discovery names no host. */
-type Invitation = "always" | "detected";
+/**
+ * Whether the flow offers a connect surface: only when discovery names a host, always, or never.
+ * `never` is a host that decides for itself, such as a domain already ready without DomainKit; a
+ * connected domain keeps its status and its disconnect either way.
+ */
+type Invitation = "always" | "detected" | "never";
+/**
+ * Whether the connect surface has anything to offer for this domain: a provider that serves the
+ * zone, a connection discovery already found, one the owner already holds, or a command already
+ * running. Never while a connection is held, which is what `holdsConnection` answers. `Prompt`
+ * renders on this, and `Domain.Flow` reports it so a host can order its own offers beside
+ * DomainKit's rather than competing with them.
+ */
+declare const offering: (controller: Controller$1, connect?: Invitation) => boolean;
 interface PromptProps extends PartProps<"div", RootState$3> {
   readonly controller: Controller$1;
   /**
    * `detected` offers nothing when discovery names no host, which is the honest answer for a
-   * domain DomainKit cannot write to. `always` offers the all-providers dialog anyway.
+   * domain DomainKit cannot write to. `always` offers the all-providers dialog anyway, and
+   * `never` offers none.
    */
   readonly connect?: Invitation;
 }
@@ -1016,19 +1054,41 @@ interface PromptProps extends PartProps<"div", RootState$3> {
  * renders unless the host application asks for the dialog anyway.
  */
 declare function Prompt({ connect, controller, ...props }: PromptProps): ReactElement | null;
+interface DisconnectDialogProps {
+  readonly controller: Controller$1;
+  /** The receipt the cleanup this dialog ran produced, for a host that tracks its own state. */
+  readonly onCleaned?: (receipt: Receipt.Model) => void;
+  readonly trigger?: ReactNode;
+}
+/**
+ * Letting a provider go, with the records DomainKit added as one decision rather than two.
+ * Confirming removes what the domain's apply receipt proves DomainKit created, then releases the
+ * connection; a plan with nothing in it is not a failure, so it goes straight to the release.
+ *
+ * The cleanup is this dialog's own, so nothing re-reads the snapshot in between: the disconnect
+ * needs the connection the cleanup just used.
+ */
+declare function DisconnectDialog({ controller, onCleaned, trigger }: DisconnectDialogProps): ReactElement;
 interface CardProps$1 extends PartProps<"div", RootState$3> {
   readonly controller: Controller$1;
+  /** The receipt a cleanup run from the disconnect dialog produced. */
+  readonly onCleaned?: (receipt: Receipt.Model) => void;
 }
-/** A connected domain: which provider holds it, and how to let it go. */
-declare function Card$1({ controller, ...props }: CardProps$1): ReactElement;
+/**
+ * A connected domain, with the prompt card's anatomy: the provider's mark, the name the customer
+ * knows it by, where the connection stands, and the one action that ends it.
+ */
+declare function Card$1({ controller, onCleaned, ...props }: CardProps$1): ReactElement;
 interface FlowProps$2 extends Omit<RootProps$5, "controller"> {
   readonly domain: string;
   readonly returnTo?: string | null;
   /** Offer the connect dialog even when discovery names no host. Defaults to `detected`. */
   readonly connect?: Invitation;
+  /** The receipt a cleanup run from the disconnect dialog produced. */
+  readonly onCleaned?: (receipt: Receipt.Model) => void;
 }
 /** Connection on its own: the card once connected, the prompt until then. */
-declare function Flow$2({ connect, domain, returnTo, ...props }: FlowProps$2): ReactElement;
+declare function Flow$2({ connect, domain, onCleaned, returnTo, ...props }: FlowProps$2): ReactElement;
 declare namespace provision_d_exports {
   export { Actions, ActionsProps, Controller$2 as Controller, Dialog, DialogProps, Flow$1 as Flow, FlowProps$1 as FlowProps, Options$1 as Options, Outcome$2 as Outcome, OutcomeProps$1 as OutcomeProps, Root$4 as Root, RootProps$4 as RootProps, RootState$2 as RootState, State$3 as State, Status$2 as Status, StatusProps$2 as StatusProps, useController$1 as useController };
 }
@@ -1240,7 +1300,7 @@ interface StatusProps$1 extends Omit<RootProps$3, "render"> {
 /** The default verification slot: a button that observes, with the evidence behind it. */
 declare function Status$1({ controller, render, ...props }: StatusProps$1): ReactElement;
 declare namespace domain_d_exports {
-  export { ActionsSlotProps, ConnectionSlotProps, Flow, FlowProps, FlowState, RecordsSlotProps, Slots, VerificationSlotProps };
+  export { ActionsSlotProps, ConnectionSlotProps, Flow, FlowProps, FlowState, RecordsSlotProps, Review, Slots, VerificationSlotProps };
 }
 interface RecordsSlotProps {
   readonly records: ReadonlyArray<DnsRecord.Model>;
@@ -1278,9 +1338,31 @@ interface Slots {
   /** Defaults to `Connect.Card` once connected and `Connect.Prompt` until then. */
   readonly connection?: (props: ConnectionSlotProps) => ReactNode;
 }
+/**
+ * What DomainKit has to say about this domain, on the part's data attributes, in `className` and
+ * `style` callbacks, and through `onState`. A host reads `connected` and `offering` to order its
+ * own offers beside DomainKit's: an offer of its own competes while `offering` is true, and a
+ * domain DomainKit holds needs none.
+ */
 interface FlowState extends Record<string, unknown> {
   readonly connection: State$1["_tag"];
   readonly provisioning: State$3["_tag"];
+  /**
+   * DomainKit holds a connection for this domain, including while a command it started over that
+   * connection is still running. `offering` is never true at the same time.
+   */
+  readonly connected: boolean;
+  /** The connect surface has something to offer, so a host's own offer would compete with it. */
+  readonly offering: boolean;
+  /** Who holds the connection, or whose nameservers serve the zone. */
+  readonly provider: string | null;
+  /**
+   * The apply receipt this domain's latest provisioning attempt produced, which is what cleanup
+   * plans from. A host's own "remove this domain" surface offers cleanup only when there is one.
+   */
+  readonly receiptId: Receipt.ReceiptId | null;
+  /** `receiptId !== null`: DomainKit applied records here and can prove which. */
+  readonly applied: boolean;
 }
 interface FlowProps extends Omit<PartProps<"div", FlowState>, "children"> {
   readonly domain: string;
@@ -1297,16 +1379,26 @@ interface FlowProps extends Omit<PartProps<"div", FlowState>, "children"> {
   readonly readOnly?: boolean;
   /**
    * Offer the connect dialog even when discovery names no host, for a host application that lets
-   * a customer connect a provider the domain's nameservers do not point at. Defaults to `detected`.
+   * a customer connect a provider the domain's nameservers do not point at, or `never` for a
+   * domain the host has already settled another way. Defaults to `detected`.
    */
   readonly connect?: Invitation;
+  /** Fires whenever what DomainKit has to say about this domain changes, and once on mount. */
+  readonly onState?: (state: FlowState) => void;
+  /**
+   * `auto` plans and opens the review the moment a connection lands, so connecting and adding the
+   * records is one pass rather than three. `manual` waits for the trigger.
+   */
+  readonly review?: Review;
 }
+/** Whether the flow opens the plan itself once a connection lands, or waits to be asked. */
+type Review = "auto" | "manual";
 /**
  * The whole lifecycle for one domain: connect, review, apply, observe, clean up. The flow renders
  * only what the transport declares, and every part of it is a slot with a default. It adds no
  * layout containers of its own, so a host's grid can place the slot output directly.
  */
-declare function Flow({ connect, domain, onApplied, onCleaned, readOnly, requirements, returnTo, slots, ...props }: FlowProps): ReactElement;
+declare function Flow({ connect, domain, onApplied, onCleaned, onState, readOnly, requirements, returnTo, review, slots, ...props }: FlowProps): ReactElement;
 //#endregion
 //#region src/icons.d.ts
 /**
@@ -1314,6 +1406,8 @@ declare function Flow({ connect, domain, onApplied, onCleaned, readOnly, require
  * an icon prop of its own, so a host swaps the whole set once on `DomainKit.Root`.
  */
 interface Icons {
+  /** Points at what a control opens: the provider menu's own marker. */
+  readonly chevron: ReactNode;
   readonly close: ReactNode;
   readonly copied: ReactNode;
   readonly copy: ReactNode;
@@ -1325,6 +1419,7 @@ interface Icons {
   readonly warning: ReactNode;
 }
 declare const defaultIcons: {
+  readonly chevron: import("react/jsx-runtime").JSX.Element;
   readonly close: import("react/jsx-runtime").JSX.Element;
   readonly copied: import("react/jsx-runtime").JSX.Element;
   readonly copy: import("react/jsx-runtime").JSX.Element;
@@ -1351,7 +1446,11 @@ interface Catalog {
   readonly close: string;
   readonly retry: string;
   readonly approve: string;
+  /** The provisioning dialog's primary action: what it adds, and how many. */
+  readonly addRecords: (count: number) => string;
   readonly decline: string;
+  /** Why the primary action is unavailable: every operation the plan holds is blocked. */
+  readonly everyRecordConflicts: string;
   readonly reviewChanges: string;
   readonly cleanUp: string;
   readonly checkDns: string;
@@ -1361,6 +1460,17 @@ interface Catalog {
   readonly moreOptions: string;
   /** Reveals the providers the dialog narrowed away. */
   readonly useAnotherProvider: string;
+  /** Opens the token form where a provider also offers a method the customer clicks through. */
+  readonly useTokenInstead: string;
+  /** Returns from one method's form to the provider's methods. */
+  readonly back: string;
+  /** The connected card's own line, beside the provider's name. */
+  readonly connected: string;
+  readonly needsReconnect: string;
+  /** The disconnect dialog's scope question, when the connection serves other domains too. */
+  readonly disconnectScope: string;
+  readonly disconnectThisDomain: string;
+  readonly disconnectEveryDomain: (count: number) => string;
   readonly copy: string;
   readonly copied: string;
   readonly copyZone: string;
@@ -1391,7 +1501,18 @@ interface Catalog {
   readonly notConnected: string;
   readonly reconnectRequired: (provider: string) => string;
   readonly disconnectTitle: (provider: string) => string;
-  readonly disconnectConsent: string;
+  /**
+   * What disconnecting means, in the present. The default names DomainKit as what stops managing
+   * the records; a host application overrides the key to name itself.
+   */
+  readonly disconnectConsent: (domain: string, provider: string) => string;
+  /**
+   * The option inside the disconnect dialog, over the records it would remove. Only this domain's
+   * apply receipt proves what DomainKit created, so the words say which records go.
+   */
+  readonly disconnectWithCleanup: (count: number) => string;
+  /** What the listed records do when that option is off. */
+  readonly disconnectKeepsRecords: (provider: string) => string;
   readonly detachConsent: string;
   readonly detached: string;
   readonly reusableConnections: string;
@@ -1463,7 +1584,8 @@ interface Catalog {
 /** What an outcome says: a heading the customer reads first, then what to do about it. */
 interface Outcome {
   readonly title: string;
-  readonly description: string;
+  /** What to do about it. Absent where the title has already said the whole of it. */
+  readonly description?: string;
 }
 /**
  * What the flow was doing when it failed. The reason alone cannot name the provider a customer