@mittwald/flow-remote-vue-components 0.0.0-stage → 1.5.0-next.35

package/USAGE.md

@@ -0,0 +1,471 @@
+# Using Flow Remote from Vue — guide for agents and developers
+
+How to build an **mStudio extension** with
+`@mittwald/flow-remote-vue-components`.
+
+> **Beta.** Extensions can be built against it, but the API is exempt from
+> Flow's breaking-change promise until the beta ends. Everything else in this
+> repository follows deprecate-don't-break — this package will too, once every
+> gap below is closed or recorded as permanent and the surface has settled
+> ([ADR 0007](https://github.com/mittwald/flow/blob/main/docs/adr/0007-beta-packages.md)).
+
+This package's components are generated from
+[`@mittwald/flow-react-components`](https://www.npmjs.com/package/@mittwald/flow-react-components)
+and have the same names and props. **Read that package's `USAGE.md` first** —
+component selection, layout and spacing, what is safe to depend on, and where
+the documentation lives. It applies here unchanged.
+
+Its remote counterpart,
+[`@mittwald/flow-remote-react-components`](https://www.npmjs.com/package/@mittwald/flow-remote-react-components),
+documents what changes because your UI renders across a process boundary — which
+components exist remotely, which props do not cross, what survives
+serialization. **That applies here unchanged too**: both packages drive the same
+`flr-*` elements.
+
+What follows is only what is different because you write Vue.
+
+## Installation
+
+```shell
+pnpm add @mittwald/flow-remote-vue-components @mittwald/flow-react-components @mittwald/ext-bridge vue react react-dom
+```
+
+`@mittwald/flow-react-components` is a **runtime and type** dependency. The
+remote connection imports its `mittwald-password-tools-js` entry to serialize
+password policies, and that entry imports `react` — without either, your bundle
+fails to build. Every component's props are typed with Flow's React prop types,
+read from that package's declarations. `@mittwald/ext-bridge` is needed because
+`RemoteRoot` imports it; `react` and `react-dom` are peers of
+`@mittwald/flow-react-components`. Install all of them explicitly: `yarn` and
+`npm --legacy-peer-deps` do not install peers on their own.
+
+## The model
+
+Your extension runs in a hidden iframe. It does not render DOM — it builds a
+tree of `flr-*` elements that is serialized to the mStudio host, which
+materializes it with the real Flow components. You write ordinary Vue; the
+boundary is invisible until you hit one of the limits the React package
+documents.
+
+```
+your extension (iframe)                    mStudio (host)
+RemoteRoot + these components  ─────────►  real Flow components
+```
+
+`RemoteRoot` is the entry point. It connects to the host's render root and
+initializes the extension bridge:
+
+```ts
+import { createApp, h } from "vue";
+import { RemoteRoot } from "@mittwald/flow-remote-vue-components";
+import App from "./App.vue";
+
+createApp({
+  render: () => h(RemoteRoot, null, { default: () => h(App) }),
+}).mount("#app");
+```
+
+The full explainer:
+<https://github.com/mittwald/flow/blob/main/docs/remote-ui.md>.
+
+## Writing components
+
+Props keep their Flow names. Events keep their Flow names too, minus `on`:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  Button,
+  Heading,
+  Section,
+  Text,
+} from "@mittwald/flow-remote-vue-components";
+
+const pilots = ref(0);
+</script>
+
+<template>
+  <Section>
+    <Heading>Squadron</Heading>
+    <Text>{{ pilots }} pilots ready</Text>
+    <Button color="success" @press="pilots++">Add a pilot</Button>
+  </Section>
+</template>
+```
+
+| Flow / React                     | Vue                                                |
+| -------------------------------- | -------------------------------------------------- |
+| `isDisabled={true}`              | `:is-disabled="true"` or `:isDisabled="true"`      |
+| `onPress={fn}`                   | `@press="fn"`, `@press-change` for `onPressChange` |
+| `className="…"`                  | `class="…"`                                        |
+| `children`                       | the default slot                                   |
+| a `ReactNode` prop (`emptyView`) | the named slot `#emptyView`                        |
+| `value` plus `onChange`          | `v-model="name"`                                   |
+| `isOpen` plus `onOpenChange`     | `v-model:is-open="open"`                           |
+
+`v-model` works on every prop Flow makes controllable — the ones with a
+`default*` sibling (`value`/`defaultValue`, `isOpen`/`defaultOpen`). A bare
+`v-model` binds `value`, or `isSelected` on a checkbox or a switch, or
+`selectedKey`; a named one binds the prop it names. `.trim` and `.number` apply.
+A `v-model` the component has nothing for warns in the console.
+
+```vue
+<TextField v-model.trim="name"><Label>Name</Label></TextField>
+<Checkbox v-model="accepted">Accept the terms</Checkbox>
+```
+
+Change data the way Vue does — in place is fine. `points.value.push(point)`
+reaches a chart just as a new array does.
+
+A prop typed `ReactNode` in Flow is a **slot** here, not a prop — rendered
+output does not survive the boundary as data:
+
+```vue
+<CartesianChart :data="data" height="300px">
+  <template #emptyView>
+    <IllustratedMessage>
+      <Heading>No data available</Heading>
+    </IllustratedMessage>
+  </template>
+  <Area data-key="Shields" />
+</CartesianChart>
+```
+
+## Icons
+
+Flow's icons are Vue components here, under the same names as in React:
+
+```vue
+<Button>
+  <IconDownload />
+  Download
+</Button>
+```
+
+They take Flow's `Icon` props (`size`, `color`, `aria-label`) and come from the
+same package as everything else.
+
+For an icon that is **not** in Flow's set — including anything from
+`@mittwald/flow-icons-pro`, which renders FontAwesome Pro and has no Vue build —
+put the SVG inside `Icon` yourself. Plain elements travel through the remote
+tree like any other node, and `Icon` gives them Flow's sizing and colour:
+
+```vue
+<Icon>
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
+    <path d="M10 3a7 7 0 1 0 0 14a7 7 0 0 0 0 -14" />
+    <path d="M21 21l-6 -6" />
+  </svg>
+</Icon>
+```
+
+To replace Flow's icons everywhere instead of one at a time, wrap the app in
+`IconSetProvider`. Each entry is a component rendering an `<svg>`, and Flow's
+`Icon` still supplies the sizing, the colour and the ARIA around it:
+
+```vue
+<IconSetProvider :set="{ Close: MyCloseIcon, Delete: MyDeleteIcon }">
+  <App />
+</IconSetProvider>
+```
+
+The set is partial: an icon you leave out keeps Flow's. This is the component to
+reach for if you license FontAwesome Pro — `@mittwald/flow-icons-pro` is React
+only, so there is nothing to import, but your own build of it goes here.
+
+## Writing JSX instead of templates
+
+Every component here is a plain Vue component, so JSX works — set
+`jsxImportSource` and write the tree the way the React examples do:
+
+```tsx
+/** @jsxImportSource vue */
+<Section>
+  <Heading>Fleet</Heading>
+  <Button onPress={launch}>Launch</Button>
+</Section>
+```
+
+Named and scoped slots are an object child:
+`<List>{{ default: ({ data }) => … }}</List>`.
+
+Two rough edges are Vue's, not this package's. `vue/jsx-runtime` hands a
+component its children as a value rather than as a slot function, so Vue warns
+"Non-function value encountered for default slot" once per element. A runtime of
+your own that wraps them silences it. The slot has to build fresh vnodes on
+every call rather than return the ones JSX built: a component calls its slot on
+every render of its own, and Vue mounts a vnode in place, so handing it the same
+nodes twice loses state (a date-range popover closed between two clicks):
+
+```ts
+import { cloneVNode, h, isVNode, type VNode } from "vue";
+
+const freshCopy = (children: unknown): unknown => {
+  if (Array.isArray(children)) return children.map(freshCopy);
+  if (!isVNode(children)) return children;
+  const copy = cloneVNode(children);
+  if (Array.isArray(copy.children)) {
+    copy.children = copy.children.map(freshCopy) as VNode[];
+  }
+  return copy;
+};
+
+// inside jsx(), for a component's default slot:
+return h(type, attributes, { default: () => freshCopy(children) });
+```
+
+And Vue's JSX namespace has no `ElementChildrenAttribute`, so TypeScript checks
+children against the props; declaring `children?: unknown` on
+`JSX.IntrinsicAttributes` is the fix.
+`apps/remote-dom-demo/src/app/remote-vue/_lib/jsx-runtime.ts` in the Flow
+repository is both, in one file — and passes `<>…</>` through as a fragment and
+takes a function child (`<Comp>{(props) => …}</Comp>`) as the default slot.
+
+## The components that are not generated
+
+Flow's overlays, actions and providers are React compositions rather than remote
+elements, so this package rebuilds them in Vue. They are imported from the same
+place and behave the same way:
+
+`Modal`, `ModalTrigger`, `Popover`, `PopoverTrigger`, `LightBox`,
+`LightBoxTrigger`, `Action`, `ActionBatch`, `NotificationProvider`,
+`SettingsProvider`, `DeprecationWarningProvider`, `CountryOptions`, `Wrap`,
+`BrowserOnly`, `LoadingIndicator`, `Form`.
+
+An overlay opens from its trigger, or from a controller you hold yourself.
+`useModalController()` inside a modal hands back that modal's controller, as in
+Flow; `useOverlayController()` without a type always makes a new one. And
+`controller.close()` asks first on a `confirm-on-close` modal —
+`close({ bypassConfirmation: true })` does not:
+
+```vue
+<script setup lang="ts">
+import {
+  Action,
+  ActionGroup,
+  Button,
+  Content,
+  Heading,
+  Modal,
+  ModalTrigger,
+} from "@mittwald/flow-remote-vue-components";
+</script>
+
+<template>
+  <ModalTrigger>
+    <Button>New squadron</Button>
+    <Modal>
+      <Heading>New squadron</Heading>
+      <Content>Rally your pilots.</Content>
+      <ActionGroup>
+        <Action close-modal>
+          <Button color="success">Create</Button>
+        </Action>
+      </ActionGroup>
+    </Modal>
+  </ModalTrigger>
+</template>
+```
+
+Two differences from the React versions are worth knowing:
+
+- **A composite reaches its own children, not the whole subtree.** Flow uses a
+  React context to configure the components inside a `Modal` or an `Action`;
+  there is no equivalent here, so a `Heading` nested one component deeper than
+  the `Modal` expects is left unconfigured. Keep them direct children.
+- **`Action` runs, reports and closes.** It has no confirmation modal of its own
+  (Flow's `slot="actionConfirm"`): an `onAction` drives the button's pending,
+  succeeded and failed states, and `close-modal` closes the surrounding overlay.
+
+A modal can still protect unsaved changes, the same way React's does:
+
+```vue
+<Modal confirm-on-close>
+  <Heading>New squadron</Heading>
+  <Content>
+    <TextField is-required><Label>Squadron name</Label></TextField>
+  </Content>
+  <ActionGroup>
+    <Action close-modal><Button color="success">Create</Button></Action>
+  </ActionGroup>
+</Modal>
+```
+
+Escape, a click outside and any `Action close-modal` in the body then ask first.
+The actions in the `ActionGroup` do not — the footer is the deliberate way out,
+which is the rule Flow's props context writes as well.
+
+## The list
+
+`List` is here, and it is configured by the elements inside it — the same shape
+Flow's React list has. They render nothing; they describe the list.
+
+```vue
+<script setup lang="ts">
+import {
+  Heading,
+  List,
+  ListFilter,
+  ListItem,
+  ListItemView,
+  ListSearch,
+  ListStaticData,
+} from "@mittwald/flow-remote-vue-components";
+
+const crew = [{ name: "Ellen Ripley", rank: "Warrant Officer" }];
+</script>
+
+<template>
+  <List aria-label="Crew" setting-storage-key="crew" accordion>
+    <ListStaticData :data="crew" />
+    <ListSearch auto-submit />
+    <ListFilter property="rank" name="Rank" mode="some" />
+    <ListItem v-slot="{ data }" :text-value="(d) => d.name">
+      <ListItemView>
+        <Heading>{{ data.name }}</Heading>
+      </ListItemView>
+    </ListItem>
+  </List>
+</template>
+```
+
+The item type comes from the data: there is no `typedList`, because the slot
+already carries it.
+
+`setting-storage-key` persists the view settings — the sorting, the filters, the
+view mode, the search — but only inside a `SettingsProvider`, as in React. It
+takes React's props and writes React's format, so a list reads what the React
+binding stored under the same keys:
+
+```vue
+<SettingsProvider type="localStorage" storage-key="squadron-settings">
+  <List aria-label="Crew" setting-storage-key="crew">…</List>
+</SettingsProvider>
+```
+
+`type="custom"` takes a `store` with an async `load()` and `store(settings)`
+instead. The children render once the settings are loaded, and a new `id` loads
+them again — from the backend the props name at that point.
+
+**Loading takes one of two elements.** `ListLoaderAsync` takes a function that
+returns a promise:
+
+```vue
+<ListLoaderAsync :loader="loadCrew" manual-pagination />
+```
+
+```ts
+const loadCrew = async (options) => {
+  const response = await api.getCrew({
+    limit: options.pagination?.limit,
+    skip: options.pagination?.offset,
+  });
+
+  return { data: response.items, itemTotalCount: response.total };
+};
+```
+
+`ListLoaderComposable` takes a **composable** — anything that has to run in a
+`setup()`, which a query library's `useQuery` does:
+
+```vue
+<ListLoaderComposable :loader="useCrew" manual-filtering />
+```
+
+```ts
+import type { ListComposableDataLoader } from "@mittwald/flow-remote-vue-components";
+
+const useCrew: ListComposableDataLoader<CrewMember> = (options) => {
+  const result = ref<{ data: CrewMember[]; itemTotalCount: number }>();
+
+  /* Re-runs whenever a filter, the sorting or the search changes. */
+  watchEffect(async () => {
+    const response = await api.getCrew(options());
+    result.value = { data: response.items, itemTotalCount: response.total };
+  });
+
+  return result;
+};
+```
+
+`options` is a **getter**, not a value: the composable is called once per batch,
+and reading it inside a `computed`, a `watch` or a query key is what makes a
+changed filter reach the source. Return a result, a ref or a getter; `undefined`
+keeps the batch loading.
+
+The three flags — `manual-pagination`, `manual-filtering`, `manual-sorting` —
+say which of those jobs the source does itself. What it is not told, it must not
+do: a source that paginates but is sent no pagination returns its first page
+forever.
+
+An async loader that reads something besides the query — a route parameter, a
+selected project — names it in `dependencies`, and a change loads every batch
+again, as in React:
+
+```vue
+<ListLoaderAsync :loader="loadCrew" :dependencies="[projectId]" />
+```
+
+`useListMetadata<T>()` reads back whatever the loader sent beside its data.
+
+The list follows its children: a filter whose `values` arrive later, a changed
+sorting name, new data. `setting-storage-key`, `get-item-id`, `batch-size` and
+`default-view-mode` are read when the list is built — give the `List` a new
+`key` to change them.
+
+**The table view's elements are flat, not nested.** React writes
+`<List.Table><List.TableHeader><List.TableColumn>`; here the columns and cells
+are direct children of the `List`, because the list reads its own children and
+does not walk into another component's slot. `ListTable`, `ListTableHeader`,
+`ListTableBody` and `ListTableRow` are there for their props, and a `ListTable`
+with no columns beside it throws rather than rendering a table view with nothing
+in it.
+
+```vue
+<List aria-label="Crew" default-view-mode="table">
+  <ListStaticData :data="crew" />
+  <ListTableColumn>Name</ListTableColumn>
+  <ListTableColumn>Rank</ListTableColumn>
+  <ListTableCell v-slot="{ data }">{{ data.name }}</ListTableCell>
+  <ListTableCell v-slot="{ data }">{{ data.rank }}</ListTableCell>
+</List>
+```
+
+## What is missing
+
+- **`typedList`, the list's `onChange`, and `infiniteScroll`.** The first has no
+  purpose here (the `ListItem` slot carries the item type); the last cannot work
+  across the boundary, in React either — the observer it needs watches an
+  element that lives in your iframe and is never on screen.
+- **Some of the list's finer props:** `settingsStorageDefaults`, a custom
+  `render` for `ListSearch` and the search field's props beyond `auto-submit`
+  and `auto-focus`, and an item's `loadingView`.
+- **`IntlProvider`.** React's sets the locale for what renders locally; a Vue
+  app renders nothing locally. `useLanguage()` reports the host's language.
+- **`ComponentDefaultsProvider`.** Its two settings belong to React's Suspense
+  and to the react-hook-form integration, neither of which exists here.
+- **The react-hook-form integration.** Use `Form` and read the submitted
+  `FormData`, or bring your own Vue form library.
+
+## Composables
+
+| Composable                        | What it gives you                                  |
+| --------------------------------- | -------------------------------------------------- |
+| `useOverlayController(type?)`     | open, close and toggle an overlay from anywhere    |
+| `useModalController()`            | the surrounding modal's controller, or a new one   |
+| `useNotificationController()`     | raise and dismiss notifications                    |
+| `useRemoteConnection()`           | the connection to the host, once it is established |
+| `useLanguage()`                   | the backoffice's language                          |
+| `useWarnDeprecation()`            | report a deprecated path you still use             |
+| `useIsMounted()`, `useOnChange()` | the small React helpers Flow exports               |
+| `injectContextIcon(name)`         | the icon a surrounding `IconSetProvider` supplies  |
+| `useListMetadata()`               | what a list's loader sent beside its data          |
+
+## Links
+
+- Flow documentation: <https://flow.mittwald.de>
+- Remote-UI explainer:
+  <https://github.com/mittwald/flow/blob/main/docs/remote-ui.md>
+- The React remote package, whose `USAGE.md` covers the boundary itself:
+  <https://www.npmjs.com/package/@mittwald/flow-remote-react-components>

package/dist/js/RemoteRoot.mjs

@@ -0,0 +1,121 @@
+import { provideRemoteContext } from "./remote-vue-components/src/composables/remoteContext.mjs";
+import { composition } from "./remote-vue-components/src/lib/composition.mjs";
+import { packageVersion } from "./remote-vue-components/src/version.mjs";
+import { DeprecationWarningProvider } from "./remote-vue-components/src/components/DeprecationWarningProvider.mjs";
+import { useWatchPathname } from "./remote-vue-components/src/composables/useWatchPathname.mjs";
+import { isRenderError } from "./remote-vue-components/src/lib/isRenderError.mjs";
+import { stringifyError } from "./remote-vue-components/src/lib/stringifyError.mjs";
+import { defineComponent, h, onErrorCaptured, onMounted, ref, watch } from "vue";
+import { connectHostRenderRootRef, connectRemoteReceiver } from "@mittwald/flow-remote-core";
+import { initExtBridge } from "@mittwald/ext-bridge/browser";
+//#region src/components/RemoteRoot.ts
+/**
+* Hides the remote tree without unmounting it: the elements have to exist and
+* mutate, because those mutations are the protocol — the host renders the
+* visible output.
+*/
+var hiddenStyle = {
+	visibility: "hidden",
+	height: 0,
+	width: 0,
+	border: "none",
+	position: "absolute",
+	marginLeft: "-9999px"
+};
+/**
+* Connects a Vue app to the mStudio host and renders its children into the
+* remote tree.
+*
+* Everything below it renders `flr-*` elements, never visible DOM — see
+* `docs/remote-ui.md`.
+*/
+var RemoteRoot = defineComponent({
+	name: "RemoteRoot",
+	props: {
+		/** Forwarded to the host, which shows its own loading state. */
+		isLoading: {
+			type: Boolean,
+			default: void 0
+		},
+		/**
+		* Internal use only: renders against a receiver in the same realm instead
+		* of connecting to a parent frame.
+		*/
+		__remoteReceiver: {
+			type: Object,
+			default: void 0
+		}
+	},
+	emits: { hostPathnameChanged: (pathname) => typeof pathname === "string" },
+	setup(props, { slots, emit }) {
+		const rootRef = ref();
+		const connection = ref();
+		const language = ref();
+		const isConnected = ref(false);
+		const failure = ref();
+		const reportedComponents = /* @__PURE__ */ new Set();
+		provideRemoteContext({
+			connection,
+			language,
+			reportComponentUsage: (component) => {
+				if (reportedComponents.has(component)) return;
+				reportedComponents.add(component);
+				connection.value?.imports.reportEvent?.({
+					event: "ComponentRendered",
+					data: { component }
+				})?.catch(() => {});
+			}
+		});
+		const setIsLoading = () => {
+			if (props.isLoading !== void 0) connection.value?.imports.setIsLoading(props.isLoading);
+		};
+		watch(() => props.isLoading, setIsLoading);
+		useWatchPathname((pathname) => connection.value?.imports.setNavigationState({
+			pathname,
+			isPending: false
+		}));
+		onErrorCaptured((error, _instance, info) => {
+			if (isRenderError(info)) connection.value?.imports.setError(stringifyError(error));
+		});
+		onMounted(() => {
+			const root = rootRef.value;
+			if (!root) return;
+			if (props.__remoteReceiver) {
+				connectRemoteReceiver(root, props.__remoteReceiver.connection);
+				isConnected.value = true;
+				return;
+			}
+			initExtBridge();
+			connectHostRenderRootRef({
+				onPathnameChanged: (pathname) => emit("hostPathnameChanged", pathname),
+				onHostError: (error) => {
+					failure.value = new Error(error);
+				},
+				packageVersion
+			})(root)?.then(async (hostConnection) => {
+				connection.value = hostConnection;
+				setIsLoading();
+				const hostConfig = await hostConnection.imports.getHostConfig();
+				language.value = hostConfig.language?.trim() || void 0;
+				isConnected.value = true;
+			}).catch((error) => {
+				failure.value = error;
+			});
+		});
+		return () => {
+			if (failure.value) throw failure.value;
+			const children = isConnected.value ? h(DeprecationWarningProvider, { onWarning: (message) => {
+				connection.value?.imports.reportDeprecation?.(message)?.catch(() => {});
+			} }, { default: () => slots.default?.() }) : void 0;
+			return h("div", {
+				ref: rootRef,
+				style: props.__remoteReceiver ? hiddenStyle : {}
+			}, children);
+		};
+	}
+});
+composition(RemoteRoot);
+//#endregion
+export { RemoteRoot, RemoteRoot as default };
+
+//# sourceMappingURL=RemoteRoot.mjs.map

package/dist/js/RemoteRoot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteRoot.mjs","names":[],"sources":["../../src/components/RemoteRoot.ts"],"sourcesContent":["import { DeprecationWarningProvider } from \"@/components/DeprecationWarningProvider\";\nimport { provideRemoteContext } from \"@/composables/remoteContext\";\nimport { useWatchPathname } from \"@/composables/useWatchPathname\";\nimport { isRenderError } from \"@/lib/isRenderError\";\nimport { stringifyError } from \"@/lib/stringifyError\";\nimport { packageVersion } from \"@/version\";\nimport {\n  connectHostRenderRootRef,\n  connectRemoteReceiver,\n  type RemoteReceiver,\n  type RemoteToHostConnection,\n} from \"@mittwald/flow-remote-core\";\nimport { initExtBridge } from \"@mittwald/ext-bridge/browser\";\nimport {\n  defineComponent,\n  h,\n  onErrorCaptured,\n  onMounted,\n  ref,\n  watch,\n  type PropType,\n  type StyleValue,\n} from \"vue\";\nimport { composition } from \"@/lib/composition\";\n\n/**\n * Hides the remote tree without unmounting it: the elements have to exist and\n * mutate, because those mutations are the protocol — the host renders the\n * visible output.\n */\nconst hiddenStyle: StyleValue = {\n  visibility: \"hidden\",\n  height: 0,\n  width: 0,\n  border: \"none\",\n  position: \"absolute\",\n  marginLeft: \"-9999px\",\n};\n\n/**\n * Connects a Vue app to the mStudio host and renders its children into the\n * remote tree.\n *\n * Everything below it renders `flr-*` elements, never visible DOM — see\n * `docs/remote-ui.md`.\n */\nexport const RemoteRoot = defineComponent({\n  name: \"RemoteRoot\",\n\n  props: {\n    /** Forwarded to the host, which shows its own loading state. */\n    isLoading: { type: Boolean, default: undefined },\n    /**\n     * Internal use only: renders against a receiver in the same realm instead\n     * of connecting to a parent frame.\n     */\n    __remoteReceiver: {\n      type: Object as PropType<RemoteReceiver>,\n      default: undefined,\n    },\n  },\n\n  emits: {\n    hostPathnameChanged: (pathname: string) => typeof pathname === \"string\",\n  },\n\n  setup(props, { slots, emit }) {\n    const rootRef = ref<HTMLDivElement>();\n    const connection = ref<RemoteToHostConnection>();\n    const language = ref<string>();\n    const isConnected = ref(false);\n    const failure = ref<unknown>();\n\n    const reportedComponents = new Set<string>();\n\n    provideRemoteContext({\n      connection,\n      language,\n      reportComponentUsage: (component) => {\n        if (reportedComponents.has(component)) {\n          return;\n        }\n        reportedComponents.add(component);\n\n        void connection.value?.imports\n          .reportEvent?.({ event: \"ComponentRendered\", data: { component } })\n          ?.catch(() => {\n            // ignore: host does not support event reporting\n          });\n      },\n    });\n\n    const setIsLoading = () => {\n      if (props.isLoading !== undefined) {\n        connection.value?.imports.setIsLoading(props.isLoading);\n      }\n    };\n\n    watch(() => props.isLoading, setIsLoading);\n\n    useWatchPathname((pathname) =>\n      connection.value?.imports.setNavigationState({\n        pathname,\n        isPending: false,\n      }),\n    );\n\n    /*\n     * A render error in the extension is not the host's error to guess at: the\n     * host shows its own failure state and the message travels with it. Any\n     * other error — a hook, a watcher, an event handler, sync or async — is\n     * left to the app. Every error goes on to `app.config.errorHandler`.\n     */\n    onErrorCaptured((error, _instance, info) => {\n      if (isRenderError(info)) {\n        void connection.value?.imports.setError(stringifyError(error));\n      }\n    });\n\n    onMounted(() => {\n      const root = rootRef.value;\n      if (!root) {\n        return;\n      }\n\n      if (props.__remoteReceiver) {\n        void connectRemoteReceiver(root, props.__remoteReceiver.connection);\n        isConnected.value = true;\n        return;\n      }\n\n      initExtBridge();\n\n      void connectHostRenderRootRef({\n        onPathnameChanged: (pathname) => emit(\"hostPathnameChanged\", pathname),\n        onHostError: (error) => {\n          failure.value = new Error(error);\n        },\n        packageVersion,\n      })(root)\n        ?.then(async (hostConnection) => {\n          connection.value = hostConnection;\n          setIsLoading();\n          const hostConfig = await hostConnection.imports.getHostConfig();\n          language.value = hostConfig.language?.trim() || undefined;\n          isConnected.value = true;\n        })\n        .catch((error: unknown) => {\n          failure.value = error;\n        });\n    });\n\n    return () => {\n      if (failure.value) {\n        throw failure.value;\n      }\n\n      /*\n       * The host is told about deprecated paths an extension still uses, the\n       * same way the React root reports them — that report is how mStudio\n       * learns who to inform before something is removed.\n       */\n      const children = isConnected.value\n        ? h(\n            DeprecationWarningProvider,\n            {\n              onWarning: (message: string) => {\n                void connection.value?.imports\n                  .reportDeprecation?.(message)\n                  ?.catch(() => {\n                    // ignore: host does not support deprecation reporting\n                  });\n              },\n            },\n            { default: () => slots.default?.() },\n          )\n        : undefined;\n\n      return h(\n        \"div\",\n        { ref: rootRef, style: props.__remoteReceiver ? hiddenStyle : {} },\n        children,\n      );\n    };\n  },\n});\n\ncomposition(RemoteRoot);\n\nexport default RemoteRoot;\n"],"mappings":";;;;;;;;;;;;;;;;AA8BA,IAAM,cAA0B;CAC9B,YAAY;CACZ,QAAQ;CACR,OAAO;CACP,QAAQ;CACR,UAAU;CACV,YAAY;AACd;;;;;;;;AASA,IAAa,aAAa,gBAAgB;CACxC,MAAM;CAEN,OAAO;;EAEL,WAAW;GAAE,MAAM;GAAS,SAAS,KAAA;EAAU;;;;;EAK/C,kBAAkB;GAChB,MAAM;GACN,SAAS,KAAA;EACX;CACF;CAEA,OAAO,EACL,sBAAsB,aAAqB,OAAO,aAAa,SACjE;CAEA,MAAM,OAAO,EAAE,OAAO,QAAQ;EAC5B,MAAM,UAAU,IAAoB;EACpC,MAAM,aAAa,IAA4B;EAC/C,MAAM,WAAW,IAAY;EAC7B,MAAM,cAAc,IAAI,KAAK;EAC7B,MAAM,UAAU,IAAa;EAE7B,MAAM,qCAAqB,IAAI,IAAY;EAE3C,qBAAqB;GACnB;GACA;GACA,uBAAuB,cAAc;IACnC,IAAI,mBAAmB,IAAI,SAAS,GAClC;IAEF,mBAAmB,IAAI,SAAS;IAEhC,WAAgB,OAAO,QACpB,cAAc;KAAE,OAAO;KAAqB,MAAM,EAAE,UAAU;IAAE,CAAC,CAAC,EACjE,YAAY,CAEd,CAAC;GACL;EACF,CAAC;EAED,MAAM,qBAAqB;GACzB,IAAI,MAAM,cAAc,KAAA,GACtB,WAAW,OAAO,QAAQ,aAAa,MAAM,SAAS;EAE1D;EAEA,YAAY,MAAM,WAAW,YAAY;EAEzC,kBAAkB,aAChB,WAAW,OAAO,QAAQ,mBAAmB;GAC3C;GACA,WAAW;EACb,CAAC,CACH;EAQA,iBAAiB,OAAO,WAAW,SAAS;GAC1C,IAAI,cAAc,IAAI,GACpB,WAAgB,OAAO,QAAQ,SAAS,eAAe,KAAK,CAAC;EAEjE,CAAC;EAED,gBAAgB;GACd,MAAM,OAAO,QAAQ;GACrB,IAAI,CAAC,MACH;GAGF,IAAI,MAAM,kBAAkB;IAC1B,sBAA2B,MAAM,MAAM,iBAAiB,UAAU;IAClE,YAAY,QAAQ;IACpB;GACF;GAEA,cAAc;GAEd,yBAA8B;IAC5B,oBAAoB,aAAa,KAAK,uBAAuB,QAAQ;IACrE,cAAc,UAAU;KACtB,QAAQ,QAAQ,IAAI,MAAM,KAAK;IACjC;IACA;GACF,CAAC,CAAC,CAAC,IAAI,CAAC,EACJ,KAAK,OAAO,mBAAmB;IAC/B,WAAW,QAAQ;IACnB,aAAa;IACb,MAAM,aAAa,MAAM,eAAe,QAAQ,cAAc;IAC9D,SAAS,QAAQ,WAAW,UAAU,KAAK,KAAK,KAAA;IAChD,YAAY,QAAQ;GACtB,CAAC,CAAC,CACD,OAAO,UAAmB;IACzB,QAAQ,QAAQ;GAClB,CAAC;EACL,CAAC;EAED,aAAa;GACX,IAAI,QAAQ,OACV,MAAM,QAAQ;GAQhB,MAAM,WAAW,YAAY,QACzB,EACE,4BACA,EACE,YAAY,YAAoB;IAC9B,WAAgB,OAAO,QACpB,oBAAoB,OAAO,CAAC,EAC3B,YAAY,CAEd,CAAC;GACL,EACF,GACA,EAAE,eAAe,MAAM,UAAU,EAAE,CACrC,IACA,KAAA;GAEJ,OAAO,EACL,OACA;IAAE,KAAK;IAAS,OAAO,MAAM,mBAAmB,cAAc,CAAC;GAAE,GACjE,QACF;EACF;CACF;AACF,CAAC;AAED,YAAY,UAAU"}

package/dist/js/components-base/src/action/ActionState.mjs

@@ -0,0 +1,85 @@
+import { action, computed, makeObservable, observable } from "mobx";
+//#region ../components-base/src/action/ActionState.ts
+/** How long each state lasts, in ms. */
+var actionStateDurations = {
+	/** An async action counts as pending only after this long. */
+	pending: 1e3,
+	succeeded: 800,
+	failed: 2e3
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* What an `Action` shows on its button: executing, pending, then succeeded or
+* failed for a moment, then idle again.
+*
+* A synchronous action shows success only with `showFeedback`, an async one
+* unless `showFeedback` is `false`. A failure is shown either way.
+*/
+var ActionState = class {
+	showFeedback;
+	state = "isIdle";
+	setPendingTimeout;
+	error;
+	isAsync = false;
+	constructor() {
+		makeObservable(this, {
+			state: observable,
+			updateState: action,
+			isBusy: computed
+		});
+	}
+	updateState(newState) {
+		this.state = newState;
+	}
+	get isBusy() {
+		return this.state !== "isIdle";
+	}
+	onAsyncStart() {
+		this.clearPendingTimeout();
+		this.isAsync = true;
+		this.updateState("isExecuting");
+		this.setPendingTimeout = setTimeout(() => this.startPending(), actionStateDurations.pending);
+	}
+	async onSucceeded() {
+		await this.onDone();
+	}
+	async onFailed(error) {
+		this.error = error ?? /* @__PURE__ */ new Error("Unknown error");
+		await this.onDone();
+	}
+	withFeedback(feedback) {
+		this.showFeedback = feedback;
+		return this;
+	}
+	async startFailedFeedback() {
+		this.updateState("isFailed");
+		await sleep(actionStateDurations.failed);
+		this.resetAfterDone();
+	}
+	async startSucceededFeedback() {
+		this.updateState("isSucceeded");
+		await sleep(actionStateDurations.succeeded);
+		this.resetAfterDone();
+	}
+	resetAfterDone() {
+		this.updateState("isIdle");
+		this.isAsync = false;
+		this.error = void 0;
+	}
+	clearPendingTimeout() {
+		if (this.setPendingTimeout) clearTimeout(this.setPendingTimeout);
+	}
+	onDone() {
+		this.clearPendingTimeout();
+		if (this.error) return this.startFailedFeedback();
+		else if (this.showFeedback !== false && (this.showFeedback || this.isAsync)) return this.startSucceededFeedback();
+		else this.resetAfterDone();
+	}
+	startPending() {
+		this.updateState("isPending");
+	}
+};
+//#endregion
+export { ActionState, ActionState as default, actionStateDurations };
+
+//# sourceMappingURL=ActionState.mjs.map