@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/integrations/tanstack-query/components/feedback/VireoQueryBoundary/VireoQueryBoundary.styled.d.ts

@@ -0,0 +1,12 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type AlertProps, type BoxProps, type ButtonProps, type CircularProgressProps, type DialogProps, type IconButtonProps, type StackProps } from "@mui/material";
+import { type VireoQueryBoundaryOwnerState } from "./VireoQueryBoundary.types.js";
+type VireoQueryBoundaryStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoQueryBoundaryOwnerState>;
+export declare const VireoQueryBoundaryRoot: VireoQueryBoundaryStyledSlotComponent<BoxProps>;
+export declare const VireoQueryBoundaryLoadingIndicator: VireoQueryBoundaryStyledSlotComponent<CircularProgressProps>;
+export declare const VireoQueryBoundaryErrorAlert: VireoQueryBoundaryStyledSlotComponent<AlertProps>;
+export declare const VireoQueryBoundaryActions: VireoQueryBoundaryStyledSlotComponent<StackProps>;
+export declare const VireoQueryBoundaryRetryButton: VireoQueryBoundaryStyledSlotComponent<ButtonProps>;
+export declare const VireoQueryBoundaryErrorDetailsButton: VireoQueryBoundaryStyledSlotComponent<IconButtonProps>;
+export declare const VireoQueryBoundaryErrorDetailsDialog: VireoQueryBoundaryStyledSlotComponent<DialogProps>;
+export {};

package/dist/integrations/tanstack-query/components/feedback/VireoQueryBoundary/VireoQueryBoundary.styled.js

@@ -0,0 +1,50 @@
+import { Alert, Box, Button, CircularProgress, Dialog, IconButton, Stack, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_QUERY_BOUNDARY_NAME } from "./VireoQueryBoundary.identity.js";
+export const VireoQueryBoundaryRoot = styled(Box, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "Root",
+    overridesResolver: ({ ownerState }, styles) => [
+        styles.root,
+        ownerState.status === "loading" && styles.loading,
+        ownerState.status === "error" && styles.error,
+        ownerState.hasErrorDetails && styles.hasErrorDetails,
+    ],
+})(({ theme }) => ({
+    alignItems: "center",
+    display: "flex",
+    justifyContent: "center",
+    minHeight: theme.spacing(20),
+    padding: theme.spacing(2),
+    width: "100%",
+}));
+export const VireoQueryBoundaryLoadingIndicator = styled(CircularProgress, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "LoadingIndicator",
+    overridesResolver: (_props, styles) => styles.loadingIndicator,
+})({});
+export const VireoQueryBoundaryErrorAlert = styled(Alert, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "ErrorAlert",
+    overridesResolver: (_props, styles) => styles.errorAlert,
+})({ width: "min(100%, 36rem)" });
+export const VireoQueryBoundaryActions = styled(Stack, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "Actions",
+    overridesResolver: (_props, styles) => styles.actions,
+})(({ theme }) => ({ marginTop: theme.spacing(1.5) }));
+export const VireoQueryBoundaryRetryButton = styled(Button, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "RetryButton",
+    overridesResolver: (_props, styles) => styles.retryButton,
+})({});
+export const VireoQueryBoundaryErrorDetailsButton = styled(IconButton, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "ErrorDetailsButton",
+    overridesResolver: (_props, styles) => styles.errorDetailsButton,
+})({});
+export const VireoQueryBoundaryErrorDetailsDialog = styled(Dialog, {
+    name: VIREO_QUERY_BOUNDARY_NAME,
+    slot: "ErrorDetailsDialog",
+    overridesResolver: (_props, styles) => styles.errorDetailsDialog,
+})({});

package/dist/integrations/tanstack-query/components/feedback/VireoQueryBoundary/VireoQueryBoundary.types.d.ts

@@ -0,0 +1,107 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { Alert, Box, BoxProps, Button, CircularProgress, Dialog, IconButton, Stack } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoQueryBoundaryClasses, type VireoQueryBoundaryClassKey } from "./VireoQueryBoundary.classes.js";
+import type { VIREO_QUERY_BOUNDARY_NAME, VireoQueryBoundarySlotName } from "./VireoQueryBoundary.identity.js";
+export type VireoQueryBoundaryStatus = "loading" | "error";
+export type VireoQueryBoundaryOwnerState = {
+    status: VireoQueryBoundaryStatus;
+    hasErrorDetails: boolean;
+    retryable: boolean;
+};
+export type VireoQueryErrorFallbackContext = {
+    error: unknown;
+    retry: () => void;
+    retryable: boolean;
+};
+export type VireoQueryErrorInfo = {
+    componentStack: string | null;
+};
+export interface VireoQueryBoundaryRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoQueryBoundaryLoadingIndicatorSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoQueryBoundaryErrorAlertSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoQueryBoundaryActionsSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoQueryBoundaryRetryButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoQueryBoundaryErrorDetailsButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoQueryBoundaryErrorDetailsDialogSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoQueryBoundary}. */
+export type VireoQueryBoundarySlots = {
+    [TSlotName in VireoQueryBoundarySlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoQueryBoundary}. */
+export type VireoQueryBoundarySlotsAndSlotProps = CreateSlotsAndSlotProps<VireoQueryBoundarySlots, {
+    /** @default Box */
+    root: SlotProps<typeof Box, VireoQueryBoundaryRootSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+    /** @default CircularProgress */
+    loadingIndicator: SlotProps<typeof CircularProgress, VireoQueryBoundaryLoadingIndicatorSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+    /** @default Alert */
+    errorAlert: SlotProps<typeof Alert, VireoQueryBoundaryErrorAlertSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+    /** @default Stack */
+    actions: SlotProps<typeof Stack, VireoQueryBoundaryActionsSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+    /** @default Button */
+    retryButton: SlotProps<typeof Button, VireoQueryBoundaryRetryButtonSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+    /** @default IconButton */
+    errorDetailsButton: SlotProps<typeof IconButton, VireoQueryBoundaryErrorDetailsButtonSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+    /** @default Dialog */
+    errorDetailsDialog: SlotProps<typeof Dialog, VireoQueryBoundaryErrorDetailsDialogSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
+}>;
+/** Props owned by {@link VireoQueryBoundary}. */
+export type VireoQueryBoundaryOwnProps = VireoQueryBoundarySlotsAndSlotProps & {
+    children: React.ReactNode;
+    /** Whether the default loading fallback announces prolonged loading. Disable for a boundary covered by an announcing ancestor. @default true */
+    announceLoading?: boolean;
+    loadingFallback?: React.ReactNode;
+    errorFallback?: (context: VireoQueryErrorFallbackContext) => React.ReactNode;
+    /** @default 'Loading' */
+    loadingLabel?: string;
+    /** Delay before the default loading indicator and announcement become visible. @default VIREO_LOADING_TOKENS.revealDelay */
+    loadingRevealDelay?: number;
+    /** @default 'Something went wrong' */
+    errorTitle?: React.ReactNode;
+    /** @default 'The requested content could not be loaded.' */
+    errorMessage?: React.ReactNode;
+    /** @default 'Retry' */
+    retryLabel?: React.ReactNode;
+    /** @default 'Show error details' */
+    errorDetailsLabel?: string;
+    /** @default 'Error details' */
+    errorDetailsTitle?: React.ReactNode;
+    /** @default 'Close error details' */
+    closeErrorDetailsLabel?: string;
+    /** @default 'Copy error details' */
+    copyErrorDetailsLabel?: string;
+    /** @default 'Error details copied' */
+    copiedErrorDetailsLabel?: string;
+    selectErrorDetails?: (error: unknown) => unknown;
+    /** @default true */
+    retryable?: boolean | ((error: unknown) => boolean);
+    resetKeys?: readonly unknown[];
+    onError?: (error: unknown, info: VireoQueryErrorInfo) => void;
+    onRetry?: (error: unknown) => void;
+    /** Override or extend the utility classes applied to each slot and state. */
+    classes?: Partial<VireoQueryBoundaryClasses>;
+};
+/** Props VireoQueryBoundary inherits from its default root after excluding component-owned props. */
+export type VireoQueryBoundaryInheritedProps = Omit<BoxProps<"div">, "children" | "component">;
+/** Props accepted by {@link VireoQueryBoundary}. */
+export type VireoQueryBoundaryProps = VireoQueryBoundaryOwnProps & VireoQueryBoundaryInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_QUERY_BOUNDARY_NAME]?: VireoThemeComponent<VireoQueryBoundaryProps, VireoQueryBoundaryClassKey, VireoQueryBoundaryOwnerState, Theme>;
+    }
+}

package/dist/integrations/tanstack-query/components/feedback/VireoQueryBoundary/VireoQueryBoundary.types.js

@@ -0,0 +1 @@
+export {};

package/dist/integrations/tanstack-query/components/feedback/VireoQueryBoundary/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./VireoQueryBoundary.js";
+export * from "./VireoQueryBoundary.classes.js";
+export * from "./VireoQueryBoundary.types.js";

package/dist/integrations/tanstack-query/components/feedback/VireoQueryBoundary/index.js

@@ -0,0 +1,3 @@
+export * from "./VireoQueryBoundary.js";
+export * from "./VireoQueryBoundary.classes.js";
+export * from "./VireoQueryBoundary.types.js";

package/dist/integrations/tanstack-query/hooks/useVireoMutation/internal/MutationErrorDetailsAction.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import type { VireoMutationErrorDetails } from "../../../../../integrations/tanstack-query/hooks/useVireoMutation/useVireoMutation.types.js";
+export declare function MutationErrorDetailsAction<TDetails>({ data, options, }: {
+    data: TDetails;
+    options: VireoMutationErrorDetails<unknown, TDetails>;
+}): React.JSX.Element;

package/dist/integrations/tanstack-query/hooks/useVireoMutation/internal/MutationErrorDetailsAction.js

@@ -0,0 +1,13 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { VireoJsonViewer } from "../../../../../core/public.js";
+import { Dialog, DialogContent, DialogTitle, IconButton, Tooltip } from "@mui/material";
+import React from "react";
+export function MutationErrorDetailsAction({ data, options, }) {
+    const [open, setOpen] = React.useState(false);
+    const label = options.label ?? "Show error details";
+    const handleClose = React.useCallback(() => setOpen(false), []);
+    return (_jsxs(_Fragment, { children: [_jsx(Tooltip, { title: label, children: _jsx(IconButton, { size: "small", color: "inherit", onClick: event => {
+                        event.stopPropagation();
+                        setOpen(true);
+                    }, "aria-label": label, children: _jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M11 17h2v-6h-2v6zm1-15C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59 8 8 8 8-3.59 8-8-3.59-8-8-8zm-1-11h2V7h-2v2z" }) }) }) }), _jsxs(Dialog, { open: open, onClose: handleClose, fullWidth: true, maxWidth: "md", children: [_jsxs(DialogTitle, { sx: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 2 }, children: [options.title ?? "Error details", _jsx(IconButton, { "aria-label": options.closeLabel ?? "Close", onClick: handleClose, edge: "end", children: _jsx("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M6 6l12 12M18 6L6 18", strokeWidth: "2", strokeLinecap: "round" }) }) })] }), _jsx(DialogContent, { sx: { pt: 2.5 }, children: _jsx(VireoJsonViewer, { data: data, maxHeight: "60vh", copyLabel: options.copyLabel ?? "Copy JSON to clipboard", copiedLabel: options.copiedLabel ?? "JSON copied" }) })] })] }));
+}

package/dist/integrations/tanstack-query/hooks/useVireoMutation/useVireoMutation.d.ts

@@ -0,0 +1,4 @@
+import type { UseVireoMutationOptions } from "./useVireoMutation.types.js";
+/** Extends TanStack Query mutations with Vireo notifications and schema-validated error details. */
+export declare function useVireoMutation<TData = unknown, TError = Error, TVariables = void, TContext = unknown, TErrorDetails = unknown>({ mutationFn, successMessage, errorMessage, errorDetails, onSuccess, onError, ...options }: UseVireoMutationOptions<TData, TError, TVariables, TContext, TErrorDetails>): import("@tanstack/react-query").UseMutationResult<TData, TError, TVariables, TContext>;
+export type { UseVireoMutationOptions, VireoMutationErrorDetails, VireoMutationMessage, } from "./useVireoMutation.types.js";

package/dist/integrations/tanstack-query/hooks/useVireoMutation/useVireoMutation.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { toast } from "../../../../integrations/sonner/public.js";
+import { useMutation } from "@tanstack/react-query";
+import { MutationErrorDetailsAction } from "../../../../integrations/tanstack-query/hooks/useVireoMutation/internal/MutationErrorDetailsAction.js";
+function resolveMessage(message, value) {
+    return typeof message === "function" ? message(value) : message;
+}
+function selectDefaultErrorDetails(error) {
+    if (typeof error !== "object" || error === null || !("response" in error))
+        return error;
+    const response = error.response;
+    if (typeof response !== "object" || response === null || !("data" in response))
+        return error;
+    return response.data;
+}
+function parseErrorDetails(error, options) {
+    if (!options)
+        return null;
+    const result = options.schema.safeParse(options.select?.(error) ?? selectDefaultErrorDetails(error));
+    return result.success ? { data: result.data, options } : null;
+}
+/** Extends TanStack Query mutations with Vireo notifications and schema-validated error details. */
+export function useVireoMutation({ mutationFn, successMessage, errorMessage, errorDetails, onSuccess, onError, ...options }) {
+    return useMutation({
+        ...options,
+        mutationFn,
+        onSuccess: (...args) => {
+            onSuccess?.(...args);
+            const message = resolveMessage(successMessage, args[0]);
+            if (message == null || message === false || message === "")
+                return;
+            toast.success(message);
+        },
+        onError: (...args) => {
+            onError?.(...args);
+            const message = resolveMessage(errorMessage, args[0]);
+            if (message == null || message === false || message === "")
+                return;
+            const parsedDetails = parseErrorDetails(args[0], errorDetails);
+            toast.error(message, {
+                action: parsedDetails ? (_jsx(MutationErrorDetailsAction, { data: parsedDetails.data, options: parsedDetails.options })) : undefined,
+            });
+        },
+    });
+}

package/dist/integrations/tanstack-query/hooks/useVireoMutation/useVireoMutation.types.d.ts

@@ -0,0 +1,28 @@
+import type { UseMutationOptions } from "@tanstack/react-query";
+import type React from "react";
+import type { z } from "zod";
+export type VireoMutationMessage<TValue> = React.ReactNode | ((value: TValue) => React.ReactNode);
+export type VireoMutationErrorDetails<TError, TDetails> = {
+    /** Validates the application-selected error payload before it is rendered. */
+    schema: z.ZodType<TDetails>;
+    /** Selects the unknown payload validated by `schema`. Defaults to an Axios-style `response.data`, then the error. */
+    select?: (error: TError) => unknown;
+    /** @default 'Show error details' */
+    label?: string;
+    /** @default 'Error details' */
+    title?: React.ReactNode;
+    /** @default 'Close' */
+    closeLabel?: string;
+    /** @default 'Copy JSON to clipboard' */
+    copyLabel?: string;
+    /** @default 'JSON copied' */
+    copiedLabel?: string;
+};
+export type UseVireoMutationOptions<TData = unknown, TError = Error, TVariables = void, TContext = unknown, TErrorDetails = unknown> = Omit<UseMutationOptions<TData, TError, TVariables, TContext>, "mutationFn" | "onError" | "onSuccess"> & {
+    mutationFn: NonNullable<UseMutationOptions<TData, TError, TVariables, TContext>["mutationFn"]>;
+    successMessage?: VireoMutationMessage<TData>;
+    errorMessage?: VireoMutationMessage<TError>;
+    errorDetails?: VireoMutationErrorDetails<TError, TErrorDetails>;
+    onSuccess?: UseMutationOptions<TData, TError, TVariables, TContext>["onSuccess"];
+    onError?: UseMutationOptions<TData, TError, TVariables, TContext>["onError"];
+};

package/dist/integrations/tanstack-query/hooks/useVireoMutation/useVireoMutation.types.js

@@ -0,0 +1 @@
+export {};

package/dist/integrations/tanstack-query/public.d.ts

@@ -0,0 +1,4 @@
+export * from "./components/feedback/VireoQueryBoundary/index.js";
+export * from "./hooks/useVireoMutation/useVireoMutation.js";
+export * from "./services/createVireoQueryEngineQueries.js";
+export * from "./services/createVireoPagedSearchQueries.js";

package/dist/integrations/tanstack-query/public.js

@@ -0,0 +1,5 @@
+"use client";
+export * from "./components/feedback/VireoQueryBoundary/index.js";
+export * from "./hooks/useVireoMutation/useVireoMutation.js";
+export * from "./services/createVireoQueryEngineQueries.js";
+export * from "./services/createVireoPagedSearchQueries.js";

package/dist/integrations/tanstack-query/services/createVireoPagedSearchQueries.d.ts

@@ -0,0 +1,36 @@
+import type { PageableParams, PageableResponse } from "@vireocodedev/infrastructure/pagination";
+import { type DataTag, type InfiniteData, type OmitKeyof, type QueryFunction, type UseInfiniteQueryOptions, type UseQueryOptions } from "@tanstack/react-query";
+export type VireoPagedSearchRequestOptions = {
+    signal?: AbortSignal;
+};
+export type VireoPagedSearchQueryPolicy = {
+    staleTime: number;
+    refetchOnMount: boolean;
+    refetchOnWindowFocus: boolean;
+    refetchOnReconnect: boolean;
+};
+type VireoPagedSearchQueryKey<TFilters> = (string | PageableParams | TFilters)[];
+/**
+ * Named public-consumer shape for `queryOptions`.
+ *
+ * Without this annotation, declaration emit expands TanStack Query's `DataTag`
+ * into references to private unique symbols that strict consumers cannot name.
+ */
+type VireoPagedSearchQueryOptions<TFilters, TResult> = OmitKeyof<UseQueryOptions<TResult, Error, TResult, VireoPagedSearchQueryKey<TFilters>>, "queryFn"> & {
+    queryFn?: QueryFunction<TResult, VireoPagedSearchQueryKey<TFilters>, never>;
+    queryKey: DataTag<VireoPagedSearchQueryKey<TFilters>, TResult, Error>;
+};
+/** Named public-consumer shape for `infiniteQueryOptions`. */
+type VireoPagedSearchInfiniteQueryOptions<TFilters, TResult> = OmitKeyof<UseInfiniteQueryOptions<TResult, Error, InfiniteData<TResult, unknown>, VireoPagedSearchQueryKey<TFilters>, number>, "queryFn"> & {
+    queryFn?: QueryFunction<TResult, VireoPagedSearchQueryKey<TFilters>, number>;
+    queryKey: DataTag<VireoPagedSearchQueryKey<TFilters>, InfiniteData<TResult, unknown>, Error>;
+};
+export declare function createVireoPagedSearchQueries<TFilters, TResult extends PageableResponse<unknown>>(args: {
+    queryKeyRoot: string;
+    searchFn: (pagination: PageableParams, filters: TFilters, request?: VireoPagedSearchRequestOptions) => Promise<TResult>;
+    policy: VireoPagedSearchQueryPolicy;
+}): {
+    search: (pagination: PageableParams, filters: TFilters) => VireoPagedSearchQueryOptions<TFilters, TResult>;
+    searchInfinite: (pagination: PageableParams, filters: TFilters) => VireoPagedSearchInfiniteQueryOptions<TFilters, TResult>;
+};
+export {};

package/dist/integrations/tanstack-query/services/createVireoPagedSearchQueries.js

@@ -0,0 +1,18 @@
+import { infiniteQueryOptions, queryOptions, } from "@tanstack/react-query";
+export function createVireoPagedSearchQueries(args) {
+    const { queryKeyRoot, searchFn, policy } = args;
+    return {
+        search: (pagination, filters) => queryOptions({
+            queryKey: [queryKeyRoot, pagination, filters],
+            queryFn: async ({ signal }) => searchFn(pagination, filters, { signal }),
+            ...policy,
+        }),
+        searchInfinite: (pagination, filters) => infiniteQueryOptions({
+            queryKey: [queryKeyRoot, "infinite", pagination, filters],
+            queryFn: async ({ pageParam, signal }) => await searchFn({ ...pagination, page: Number(pageParam) }, filters, { signal }),
+            initialPageParam: 0,
+            getNextPageParam: (lastPage) => lastPage.number + 1 < lastPage.totalPages ? lastPage.number + 1 : undefined,
+            ...policy,
+        }),
+    };
+}

package/dist/integrations/tanstack-query/services/createVireoQueryEngineQueries.d.ts

@@ -0,0 +1,15 @@
+import { QueryEngineQueryKey, type QueryEngineApi, type QueryEngineEntityDefinition, type QueryEngineEntityKey, type QueryEngineEntitySummary } from "@vireocodedev/query";
+import { type DataTag, type OmitKeyof, type QueryFunction, type UseQueryOptions } from "@tanstack/react-query";
+type VireoQueryEngineQueryOptions<TData, TQueryKey extends readonly unknown[]> = OmitKeyof<UseQueryOptions<TData, Error, TData, TQueryKey>, "queryFn"> & {
+    queryFn?: QueryFunction<TData, TQueryKey, never>;
+} & {
+    queryKey: DataTag<TQueryKey, TData, Error>;
+};
+/** Creates React Query options for the framework-free QueryEngine API. */
+export declare function createVireoQueryEngineQueries(api: QueryEngineApi): {
+    listEntities: () => VireoQueryEngineQueryOptions<QueryEngineEntitySummary[], (typeof QueryEngineQueryKey.entities)[]>;
+    listEntityDefinitions: (entityKeys: QueryEngineEntityKey[]) => VireoQueryEngineQueryOptions<Partial<Record<QueryEngineEntityKey, QueryEngineEntityDefinition>>, string[]>;
+    describeEntity: (entityKey: QueryEngineEntityKey) => VireoQueryEngineQueryOptions<QueryEngineEntityDefinition, string[]>;
+};
+export type VireoQueryEngineQueries = ReturnType<typeof createVireoQueryEngineQueries>;
+export {};

package/dist/integrations/tanstack-query/services/createVireoQueryEngineQueries.js

@@ -0,0 +1,26 @@
+"use client";
+import { QueryEngineQueryKey, } from "@vireocodedev/query";
+import { queryOptions, } from "@tanstack/react-query";
+/** Creates React Query options for the framework-free QueryEngine API. */
+export function createVireoQueryEngineQueries(api) {
+    return {
+        listEntities: () => queryOptions({
+            queryKey: [QueryEngineQueryKey.entities],
+            queryFn: ({ signal }) => api.listEntities({ signal }),
+        }),
+        listEntityDefinitions: (entityKeys) => queryOptions({
+            queryKey: [QueryEngineQueryKey.entityDefinitions, ...entityKeys],
+            queryFn: async ({ signal }) => {
+                const definitions = await Promise.all(entityKeys.map(entityKey => api.describeEntity(entityKey, { signal })));
+                return definitions.reduce((byEntityKey, definition) => {
+                    byEntityKey[definition.key] = definition;
+                    return byEntityKey;
+                }, {});
+            },
+        }),
+        describeEntity: (entityKey) => queryOptions({
+            queryKey: [QueryEngineQueryKey.entityDefinition, entityKey],
+            queryFn: ({ signal }) => api.describeEntity(entityKey, { signal }),
+        }),
+    };
+}

package/dist/storybook/VireoDockedSidePanel/VireoDockedSidePanelWorkspaceFrame.d.ts

@@ -0,0 +1,6 @@
+import type React from "react";
+export type VireoDockedSidePanelWorkspaceFrameProps = {
+    children: React.ReactNode;
+};
+/** Neutral desktop workspace used by VireoDockedSidePanel executable examples. */
+export declare function VireoDockedSidePanelWorkspaceFrame({ children }: VireoDockedSidePanelWorkspaceFrameProps): React.JSX.Element;

package/dist/storybook/VireoDockedSidePanel/VireoDockedSidePanelWorkspaceFrame.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Button, Stack, Typography } from "@mui/material";
+/** Neutral desktop workspace used by VireoDockedSidePanel executable examples. */
+export function VireoDockedSidePanelWorkspaceFrame({ children }) {
+    return (_jsxs(Box, { sx: {
+            display: "flex",
+            width: "100%",
+            minWidth: 720,
+            height: 440,
+            overflow: "hidden",
+            border: 1,
+            borderColor: "divider",
+            borderRadius: 2,
+            bgcolor: "background.default",
+        }, children: [_jsxs(Box, { component: "main", sx: { flex: 1, minWidth: 0, p: 3 }, children: [_jsxs(Stack, { direction: "row", spacing: 2, sx: {
+                            alignItems: "center",
+                            justifyContent: "space-between",
+                        }, children: [_jsxs(Box, { children: [_jsx(Typography, { variant: "overline", color: "primary.main", children: "Finance workspace" }), _jsx(Typography, { variant: "h4", children: "August overview" })] }), _jsx(Button, { variant: "contained", children: "New invoice" })] }), _jsx(Typography, { color: "text.secondary", sx: { mt: 3 }, children: "The docked panel reserves space beside this workspace instead of covering it." })] }), children] }));
+}

package/dist/storybook/VireoDockedSidePanel/index.d.ts

@@ -0,0 +1 @@
+export * from "./VireoDockedSidePanelWorkspaceFrame.js";

package/dist/storybook/VireoDockedSidePanel/index.js

@@ -0,0 +1 @@
+export * from "./VireoDockedSidePanelWorkspaceFrame.js";

package/dist/storybook/VireoEventSourceStoryServer.d.ts

@@ -0,0 +1,17 @@
+import React from "react";
+export type VireoEventSourceStoryServerController = Readonly<{
+    connectionCount: number;
+    emitMessage: (data: string) => void;
+    emitNamedMessage: (eventName: string, data: string) => void;
+    interrupt: () => void;
+    resume: () => void;
+    terminate: () => void;
+}>;
+export type VireoEventSourceStoryServerProps = {
+    children: (controller: VireoEventSourceStoryServerController) => React.ReactNode;
+};
+/**
+ * Installs a deterministic in-memory EventSource while its executable
+ * Storybook example is mounted. This is developer tooling, not production UI.
+ */
+export declare function VireoEventSourceStoryServer({ children }: VireoEventSourceStoryServerProps): React.ReactNode;

package/dist/storybook/VireoEventSourceStoryServer.js

@@ -0,0 +1,106 @@
+"use client";
+import React from "react";
+/**
+ * Installs a deterministic in-memory EventSource while its executable
+ * Storybook example is mounted. This is developer tooling, not production UI.
+ */
+export function VireoEventSourceStoryServer({ children }) {
+    const [ready, setReady] = React.useState(false);
+    const [connectionCount, setConnectionCount] = React.useState(0);
+    const activeSourceRef = React.useRef(null);
+    React.useLayoutEffect(() => {
+        const originalEventSource = globalThis.EventSource;
+        const hadOriginalEventSource = "EventSource" in globalThis;
+        class StoryEventSource {
+            constructor(url, init) {
+                this.CONNECTING = StoryEventSource.CONNECTING;
+                this.OPEN = StoryEventSource.OPEN;
+                this.CLOSED = StoryEventSource.CLOSED;
+                this.readyState = StoryEventSource.CONNECTING;
+                this.onopen = null;
+                this.onerror = null;
+                this.onmessage = null;
+                this.listeners = new Map();
+                this.url = url.toString();
+                this.withCredentials = init?.withCredentials ?? false;
+                activeSourceRef.current = this;
+                setConnectionCount(count => count + 1);
+                queueMicrotask(() => this.open());
+            }
+            addEventListener(type, listener) {
+                if (listener === null)
+                    return;
+                const listeners = this.listeners.get(type) ?? new Set();
+                listeners.add(listener);
+                this.listeners.set(type, listeners);
+            }
+            removeEventListener(type, listener) {
+                if (listener === null)
+                    return;
+                this.listeners.get(type)?.delete(listener);
+            }
+            dispatchEvent(event) {
+                for (const listener of this.listeners.get(event.type) ?? []) {
+                    if (typeof listener === "function")
+                        listener.call(this, event);
+                    else
+                        listener.handleEvent(event);
+                }
+                return !event.defaultPrevented;
+            }
+            close() {
+                this.readyState = StoryEventSource.CLOSED;
+            }
+            open() {
+                if (this.readyState !== StoryEventSource.CONNECTING || activeSourceRef.current !== this)
+                    return;
+                this.readyState = StoryEventSource.OPEN;
+                this.onopen?.(new Event("open"));
+            }
+            interrupt() {
+                if (this.readyState !== StoryEventSource.OPEN || activeSourceRef.current !== this)
+                    return;
+                this.readyState = StoryEventSource.CONNECTING;
+                this.onerror?.(new Event("error"));
+            }
+            terminate() {
+                if (this.readyState === StoryEventSource.CLOSED || activeSourceRef.current !== this)
+                    return;
+                this.readyState = StoryEventSource.CLOSED;
+                this.onerror?.(new Event("error"));
+            }
+            emitMessage(data) {
+                if (this.readyState !== StoryEventSource.OPEN || activeSourceRef.current !== this)
+                    return;
+                this.onmessage?.(new MessageEvent("message", { data }));
+            }
+            emitNamedMessage(eventName, data) {
+                if (this.readyState !== StoryEventSource.OPEN || activeSourceRef.current !== this)
+                    return;
+                this.dispatchEvent(new MessageEvent(eventName, { data }));
+            }
+        }
+        StoryEventSource.CONNECTING = 0;
+        StoryEventSource.OPEN = 1;
+        StoryEventSource.CLOSED = 2;
+        globalThis.EventSource = StoryEventSource;
+        setReady(true);
+        return () => {
+            activeSourceRef.current?.close();
+            activeSourceRef.current = null;
+            if (hadOriginalEventSource)
+                globalThis.EventSource = originalEventSource;
+            else
+                Reflect.deleteProperty(globalThis, "EventSource");
+        };
+    }, []);
+    const controller = React.useMemo(() => ({
+        connectionCount,
+        emitMessage: data => activeSourceRef.current?.emitMessage(data),
+        emitNamedMessage: (eventName, data) => activeSourceRef.current?.emitNamedMessage(eventName, data),
+        interrupt: () => activeSourceRef.current?.interrupt(),
+        resume: () => activeSourceRef.current?.open(),
+        terminate: () => activeSourceRef.current?.terminate(),
+    }), [connectionCount]);
+    return ready ? children(controller) : null;
+}

package/dist/storybook/VireoIconContainer/VireoIconContainerComparisonFrame.d.ts

@@ -0,0 +1,8 @@
+import type React from "react";
+export type VireoIconContainerComparisonFrameProps = {
+    normalized: React.ReactNode;
+    original: React.ReactNode;
+    sourceDimensions: string;
+};
+/** Story presentation frame for comparing source SVG geometry with Vireo's normalized output. */
+export declare function VireoIconContainerComparisonFrame({ normalized, original, sourceDimensions, }: VireoIconContainerComparisonFrameProps): React.JSX.Element;