@civitai/blocks-react 0.73.2 → 0.74.1

package/README.md

@@ -3013,11 +3013,13 @@ from `@civitai/app-sdk/blocks` is the same thing without the hook.
 ## The `/ui` subexport
 
 Opinionated components, imported separately so a transport-only block stays lean.
-Two surfaces live here:
+Three surfaces live here:
 
 1. The **W6 component pack** — a small, Civitai-looking, self-styled component
    set you drop straight into a block.
-2. The headless, manifest-driven **`SettingsForm`** (host-themed native controls).
+2. **`WorkflowPicker`** — lets the viewer pick a posted workflow, theirs or
+   anyone's, from the Civitai catalog.
+3. The headless, manifest-driven **`SettingsForm`** (host-themed native controls).
 
 ### W6 component pack
 
@@ -3109,6 +3111,92 @@ to inject the CSS yourself (SSR, or a non-React shell)? Call
 > inside the sandboxed block; a full focus-trap is a v1 follow-up (kept
 > dependency-free here on purpose).
 
+### `WorkflowPicker`
+
+`<civitai-resource-picker>` from `@civitai/components`, set up for workflows: it
+lists `Workflows` and the retired `ComfyWorkflows` type (so older posts can be
+picked), lets the viewer switch between **their own** published workflows and
+**anyone's**, and picks one **version** (the newest by default). It calls
+`GET /api/v1/blocks/models` at `useHostOrigin()` with `useBlockToken().raw` —
+no host bridge, no extra scope.
+
+```tsx
+import { useState } from 'react';
+import { WorkflowPicker, type PickedResource } from '@civitai/blocks-react/ui';
+
+export function ChooseWorkflow() {
+  const [open, setOpen] = useState(false);
+  const [picked, setPicked] = useState<PickedResource | null>(null);
+  return (
+    <>
+      <button type="button" onClick={() => setOpen(true)}>Use a workflow</button>
+      <WorkflowPicker
+        open={open}
+        owner="mine"
+        onPick={(workflow) => {
+          setPicked(workflow);
+          setOpen(false);
+        }}
+        onDismiss={() => setOpen(false)}
+      />
+      {picked && <p>{picked.name} — {picked.versionName}</p>}
+    </>
+  );
+}
+```
+
+A pick is a `PickedResource` — `{ modelId, modelVersionId, name, versionName,
+creatorUsername, baseModel, earlyAccessDeadline?, access, owner }`; `/ui`
+re-exports it and the picker's other data types (`ResourceItem`,
+`ResourceSource`, …). Close the picker yourself in
+**both** callbacks: `open` is controlled. The picker closes itself on Escape or
+a backdrop click, and re-opens on the next render if `open` still says `true`.
+
+- 🔴 **`owner` is a UX hint, never proof of ownership.** It says which list the
+  viewer was looking at, and your app's own code can set it to anything. A
+  server that must know "this is the viewer's own workflow" checks that itself.
+- 🔴 **A "mine" list is only ever the server's.** The picker shows an error, not
+  a list, when a `mine` search comes back without `metadata.owner: 'mine'` — a
+  server older than the parameter ignores it and returns everybody's. It never
+  falls back to the public `/api/v1/models`.
+- **Early-access and paid versions are listed, with a badge.** `access` on a
+  pick is `'early-access'` (a timed paid-access gate, with its end date in
+  `earlyAccessDeadline` when the server knows it), `'paid'` (a permanent gate)
+  or `'open'`. The viewer may not be able to download a gated version later.
+- **Search is debounced** (300 ms), and a newer search cancels the one in
+  flight. A busy catalog (`429` / `503`, rate limit 150 requests per 10 s per
+  block) is retried after its `Retry-After`, twice, then offered as "Try again".
+- **An anonymous viewer** gets a sign-in message on the "mine" list as soon as
+  the catalog answers `401`, with no `REQUEST_TOKEN` to the host first — the
+  picker knows the viewer is anonymous from `useBlockContext()`. "All" works. An expired block token is not mistaken for
+  that: for a signed-in viewer, or on "All", a `401` makes the picker mint a
+  fresh token through `useBlockToken().refresh()` and retry once.
+- **Before `BLOCK_INIT`** the picker says it is not connected yet, and lists as
+  soon as the host origin lands.
+- **Under the mock host** there is no catalog to call. Pass canned results from
+  `/testing`:
+
+```tsx
+import { WorkflowPicker } from '@civitai/blocks-react/ui';
+import { fakeResourceSource } from '@civitai/blocks-react/testing';
+
+const source = fakeResourceSource({
+  mine: [
+    {
+      modelId: 1,
+      name: 'My upscale chain',
+      type: 'Workflows',
+      creatorUsername: 'me',
+      versions: [{ id: 11, name: 'v2', baseModel: 'SDXL 1.0' }],
+    },
+  ],
+});
+
+export const Picker = () => <WorkflowPicker open source={source} onPick={console.log} />;
+```
+
+Under `dev:live` it works for real: the dev token can read `/blocks/models`.
+
 ### `SettingsForm`
 
 The headless, manifest-driven settings form (its contract is intentionally
@@ -3202,6 +3290,7 @@ what went stale in [#334](https://github.com/civitai/civitai-app-starters/issues
 | `createMockHost` | A framework-agnostic fake of the embedding host — answers every `*_RESULT` message, with knobs for generation cost/latency/failure, Buzz balance, app + shared storage, consent, maturity. Returns a `MockHost`; call `.install()` and keep the returned teardown. **No network, no Buzz.** |
 | `readMockHostUrlOptions` | Reads the harness URL toggles (`?viewer` `?consent` `?fail` `?theme` `?pick` `?balance` `?latency` `?seed` …) into a `Partial<MockHostOptions>`. `Harness` applies it for you; call it directly only in a hand-rolled harness. |
 | `Harness` | The React wrapper: installs a `createMockHost` on mount, tears it down on unmount, and renders an optional on-screen outbound-message log. Takes every `MockHostOptions` field plus `applyUrlToggles` and `showLog`. |
+| `fakeResourceSource` | Canned results for `<WorkflowPicker>` (from `/ui`) or `<civitai-resource-picker>`: `fakeResourceSource({ mine, any })` filters by owner, type and query, echoes the owner it applied, and records each search on `.calls`. The mock host has no catalog, so pass it as the picker's `source`. **No network.** |
 | `installPopoverShim` | Stands in for the HTML popover API, which neither `jsdom` nor `happy-dom` implements at any version. Needed only if your own code calls `showPopover`/`hidePopover`/`togglePopover` or queries `:popover-open` — `@civitai/components`' own elements do not. Returns a `PopoverShimHandle`; inert (`installed: false`) in a real browser. **Read [Testing overlay elements](#testing-overlay-elements) first: it does not make trigger clicks work.** |
 
 <!-- TESTING-SURFACE:VALUES:END -->
@@ -3216,6 +3305,8 @@ type.
 ```text
 CannedPick
 CostSpec
+FakeResourceCanned
+FakeResourceSource
 HarnessProps
 ImageSpec
 MockBuzzBalance

package/dist/internal/fakeResourceSource.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `fakeResourceSource` — canned results for `<WorkflowPicker>` /
+ * `<civitai-resource-picker>` where there is no catalog to call: the mock host,
+ * a unit test, a story. No network.
+ *
+ * It answers the way the real endpoint does where the picker can tell:
+ * it filters by `owner`, `types` and `query`, and echoes the `owner` it applied.
+ */
+import type { ResourceItem, ResourceSearchParams, ResourceSource } from '@civitai/components/civitai-resource-picker';
+/** What a {@link fakeResourceSource} lists. */
+export interface FakeResourceCanned {
+    /** The viewer's own resources: what `owner=mine` lists. */
+    mine?: readonly ResourceItem[];
+    /**
+     * Everybody's: what `owner=any` lists. Defaults to `mine` plus nothing else,
+     * so a fake with only `mine` still shows them under "All".
+     */
+    any?: readonly ResourceItem[];
+}
+/** A {@link ResourceSource} that also records what it was asked. */
+export interface FakeResourceSource extends ResourceSource {
+    /** Every search, oldest first. */
+    readonly calls: readonly ResourceSearchParams[];
+}
+/** Canned picker results. See {@link FakeResourceCanned}. */
+export declare function fakeResourceSource(canned?: FakeResourceCanned): FakeResourceSource;
+//# sourceMappingURL=fakeResourceSource.d.ts.map

package/dist/internal/fakeResourceSource.js

@@ -0,0 +1,21 @@
+/** Canned picker results. See {@link FakeResourceCanned}. */
+export function fakeResourceSource(canned = {}) {
+    const calls = [];
+    const lists = {
+        mine: canned.mine ?? [],
+        any: canned.any ?? canned.mine ?? [],
+    };
+    return {
+        calls,
+        async search(params, signal) {
+            calls.push(params);
+            if (signal.aborted)
+                throw signal.reason ?? new DOMException('Aborted', 'AbortError');
+            const query = params.query?.trim().toLowerCase() ?? '';
+            const items = lists[params.owner].filter((item) => (params.types.length === 0 || params.types.includes(item.type)) &&
+                (query === '' || item.name.toLowerCase().includes(query)));
+            return { items: [...items], nextCursor: null, owner: params.owner };
+        },
+    };
+}
+//# sourceMappingURL=fakeResourceSource.js.map

package/dist/testing.d.ts

@@ -22,6 +22,7 @@ import { type MockHostOptions } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
 export { installPopoverShim, type PopoverShimHandle, type PopoverShimOptions, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, type MockHost, type MockHostOptions, type MockHostFailMode, type MockHostScenarioPatch, type MockGenerationScenario, type MockBuzzScenario, type MockBuzzBalance, type MockBuzzHandle, type MockStorageScenario, type MockSharedScenario, type MockSharedSeed, type MockCannedImageScan, type MockWorkflowStepInfo, type MockWorkflowQuoteFailure, type CostSpec, type ImageSpec, type CannedPick, } from './internal/mockHost.js';
+export { fakeResourceSource, type FakeResourceCanned, type FakeResourceSource, } from './internal/fakeResourceSource.js';
 /**
  * Props for the dev {@link Harness}.
  */

package/dist/testing.js

@@ -23,6 +23,7 @@ import { createMockHost, readMockHostUrlOptions, } from './internal/mockHost.js'
 export { __resetTransport as resetTransport };
 export { installPopoverShim, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, } from './internal/mockHost.js';
+export { fakeResourceSource, } from './internal/fakeResourceSource.js';
 /**
  * What the harness chrome's `consent=` readout says, from the TWO INDEPENDENT
  * booleans that describe consent in the mock host.

package/dist/ui/WorkflowPicker.d.ts

@@ -0,0 +1,37 @@
+import { type PickedResource, type ResourceOwner, type ResourceSource } from '@civitai/components/civitai-resource-picker';
+/** The two model types a posted workflow can have; `ComfyWorkflows` is the retired one. */
+export declare const WORKFLOW_PICKER_TYPES = "Workflows ComfyWorkflows";
+export interface WorkflowPickerProps {
+    /**
+     * Shows the picker. Controlled: set it back to `false` in both callbacks. The
+     * picker closes itself on Escape or a backdrop click, and re-opens on the
+     * next render if this still says `true`.
+     */
+    open: boolean;
+    /**
+     * The viewer picked a version. 🔴 `picked.owner` is a UX hint, never proof the
+     * workflow is the viewer's own — check that server-side.
+     */
+    onPick: (picked: PickedResource) => void;
+    /** The viewer closed the picker without picking. */
+    onDismiss?: () => void;
+    /** Which list shows first. Defaults to `'any'`. */
+    owner?: ResourceOwner;
+    /** Defaults to `'Choose a workflow'`. */
+    heading?: string;
+    /**
+     * Where results come from. Defaults to the App Blocks catalog
+     * (`/api/v1/blocks/models`) through this block's host origin and token. Pass
+     * `fakeResourceSource(...)` from `@civitai/blocks-react/testing` under the
+     * mock host, which has no catalog to call.
+     */
+    source?: ResourceSource;
+}
+/**
+ * A workflow picker for a block: `<civitai-resource-picker>` listing
+ * `Workflows` and `ComfyWorkflows`, wired to {@link useHostOrigin} and
+ * {@link useBlockToken} so the viewer can pick one of their own posted
+ * workflows, or anyone's.
+ */
+export declare function WorkflowPicker({ open, onPick, onDismiss, owner, heading, source, }: WorkflowPickerProps): React.JSX.Element;
+//# sourceMappingURL=WorkflowPicker.d.ts.map

package/dist/ui/WorkflowPicker.js

@@ -0,0 +1,92 @@
+import { createElement, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { blockTokenSource, defineCivitaiResourcePicker, ResourceSourceError, } from '@civitai/components/civitai-resource-picker';
+import { isSignedIn } from '@civitai/app-sdk/blocks';
+import { useBlockContext } from '../hooks/useBlockContext.js';
+import { useBlockToken } from '../hooks/useBlockToken.js';
+import { useHostOrigin } from '../hooks/useHostOrigin.js';
+/** The two model types a posted workflow can have; `ComfyWorkflows` is the retired one. */
+export const WORKFLOW_PICKER_TYPES = 'Workflows ComfyWorkflows';
+/**
+ * Answers every search while the host origin is unknown: an error the picker
+ * shows with a retry, never a silent wait. The picker searches again on its own
+ * once the real source replaces this one.
+ */
+const NOT_CONNECTED = {
+    search: async () => {
+        throw new ResourceSourceError('failed', 'Not connected to Civitai yet.');
+    },
+};
+/**
+ * A workflow picker for a block: `<civitai-resource-picker>` listing
+ * `Workflows` and `ComfyWorkflows`, wired to {@link useHostOrigin} and
+ * {@link useBlockToken} so the viewer can pick one of their own posted
+ * workflows, or anyone's.
+ */
+export function WorkflowPicker({ open, onPick, onDismiss, owner = 'any', heading = 'Choose a workflow', source, }) {
+    defineCivitaiResourcePicker();
+    const host = useHostOrigin();
+    const { raw, refresh } = useBlockToken();
+    const { ready, viewer } = useBlockContext();
+    // Read at each request, so a refreshed token is the one sent.
+    const token = useRef({ raw, refresh });
+    token.current = { raw, refresh };
+    // Defensive, and unreachable today: the live source exists only once
+    // `useHostOrigin()` is set, which happens at BLOCK_INIT — the same moment
+    // `ready` flips — so no search reads the `undefined` arm and no test covers
+    // it. It is here so that a pre-init `viewer: null` (also null) can never be
+    // read as anonymous if that ordering changes.
+    const signedIn = useRef(undefined);
+    signedIn.current = ready ? isSignedIn(viewer) : undefined;
+    const live = useMemo(() => host
+        ? blockTokenSource({
+            origin: host,
+            // After a 401: mint a new token (an expired one is routine in a
+            // tab that slept). A failed mint returns the old token, which ends
+            // the search as `unauthorized`.
+            getToken: (options) => options?.fresh
+                ? token.current.refresh().then((fresh) => fresh.raw, () => token.current.raw)
+                : token.current.raw,
+            // An anonymous viewer's `mine` 401 is "sign in", not "expired":
+            // shown at once, without a REQUEST_TOKEN round trip to the host
+            // (which would only hand back the same anonymous token).
+            signedIn: () => signedIn.current,
+        })
+        : NOT_CONNECTED, [host]);
+    const ref = useRef(null);
+    const handlers = useRef({ onPick, onDismiss });
+    handlers.current = { onPick, onDismiss };
+    // Properties, not attributes: React 18 would stringify the source.
+    useLayoutEffect(() => {
+        if (ref.current)
+            ref.current.source = source ?? live;
+    }, [source, live]);
+    // No dependency list on purpose: the element closes itself on Escape or a
+    // backdrop click, so it can disagree with `open` without the prop changing.
+    // Every render puts it back in line, which is what lets a consumer that
+    // never handled `onDismiss` open it again.
+    useLayoutEffect(() => {
+        if (ref.current && ref.current.open !== open)
+            ref.current.open = open;
+    });
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const pick = (event) => handlers.current.onPick(event.detail);
+        const dismiss = () => handlers.current.onDismiss?.();
+        el.addEventListener('pick', pick);
+        el.addEventListener('dismiss', dismiss);
+        return () => {
+            el.removeEventListener('pick', pick);
+            el.removeEventListener('dismiss', dismiss);
+        };
+    }, []);
+    return createElement('civitai-resource-picker', {
+        ref,
+        types: WORKFLOW_PICKER_TYPES,
+        noun: 'workflow',
+        owner,
+        heading,
+    });
+}
+//# sourceMappingURL=WorkflowPicker.js.map

package/dist/ui/index.d.ts

@@ -58,4 +58,7 @@ export { Collapse } from './Collapse.js';
 export type { CollapseProps } from './Collapse.js';
 export { SegmentedControl } from './SegmentedControl.js';
 export type { SegmentedControlProps, SegmentedControlItem, SegmentedControlSize, } from './SegmentedControl.js';
+export { WorkflowPicker, WORKFLOW_PICKER_TYPES } from './WorkflowPicker.js';
+export type { WorkflowPickerProps } from './WorkflowPicker.js';
+export type { PickedResource, ResourceAccess, ResourceItem, ResourceOwner, ResourcePage, ResourceSearchParams, ResourceSource, ResourceVersion, } from '@civitai/components/civitai-resource-picker';
 //# sourceMappingURL=index.d.ts.map

package/dist/ui/index.js

@@ -43,4 +43,5 @@ export { NumberInput } from './NumberInput.js';
 export { Select } from './Select.js';
 export { Collapse } from './Collapse.js';
 export { SegmentedControl } from './SegmentedControl.js';
+export { WorkflowPicker, WORKFLOW_PICKER_TYPES } from './WorkflowPicker.js';
 //# sourceMappingURL=index.js.map

package/dist/version.generated.d.ts

@@ -1,3 +1,3 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.73.2";
+export declare const VERSION = "0.74.1";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -1,4 +1,4 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.73.2";
+export const VERSION = "0.74.1";
 //# sourceMappingURL=version.generated.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.73.2",
+  "version": "0.74.1",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@civitai/components": "^0.10.0",
+    "@civitai/components": "^0.12.0",
     "@civitai/theme": "^0.5.2"
   },
   "comment-peerDependencies": "This floor is DERIVED, not chosen — the lowest published app-sdk that exports every symbol this package imports. Do not edit it without reading ./PEER_FLOOR.md (in-repo, unpublished) and tests/guards/blocks-react-peer-floor.test.mjs.",