@ttt-productions/upload-ui 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/react/deferred-upload-form-shell.d.ts

@@ -0,0 +1,39 @@
+import React, { type ReactNode, type Ref } from 'react';
+import type { MediaOriginSpec, UploadState } from '@ttt-productions/media-schemas';
+export interface DeferredUploadFormShellHandle {
+    submit: () => void;
+}
+export interface DeferredUploadFormShellProps<TVariables extends {
+    onProgress?: (s: UploadState | null) => void;
+    signal?: AbortSignal;
+}, TResult = unknown> {
+    /** The media-origin spec describing accept patterns, size caps, and label.
+     *  Consumers pass this directly — the shell does not look it up from a registry. */
+    spec: MediaOriginSpec;
+    /** Opaque caller-supplied identifier for this upload origin (e.g. "streetz", "project-file").
+     *  The shell does not interpret it; it is forwarded only via consumer-controlled callbacks. */
+    originId: string;
+    mutation: {
+        mutateAsync: (vars: TVariables) => Promise<TResult>;
+        isPending: boolean;
+    };
+    buildVariables: (file: File | null, onProgress: (s: UploadState | null) => void, signal: AbortSignal) => TVariables;
+    onSuccess?: (result: TResult) => void;
+    onError?: (err: unknown) => void;
+    /**
+     * Optional callback fired whenever the shell's internal selectedFile state
+     * changes — on user select, on user clear, and on the post-success internal
+     * reset. Forms typically use this to mirror selectedFile externally so they
+     * can compute their own submit-button `disabled` flag (e.g. require-a-file
+     * submit gating).
+     */
+    onFileChange?: (file: File | null) => void;
+    children?: ReactNode;
+}
+export declare const DeferredUploadFormShell: <TVariables extends {
+    onProgress?: (s: UploadState | null) => void;
+    signal?: AbortSignal;
+}, TResult = unknown>(props: DeferredUploadFormShellProps<TVariables, TResult> & {
+    ref?: Ref<DeferredUploadFormShellHandle>;
+}) => React.ReactElement;
+//# sourceMappingURL=deferred-upload-form-shell.d.ts.map

package/dist/react/deferred-upload-form-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-upload-form-shell.d.ts","sourceRoot":"","sources":["../../src/react/deferred-upload-form-shell.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAMZ,KAAK,SAAS,EACd,KAAK,GAAG,EACT,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAEnF,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B,CAC3C,UAAU,SAAS;IACjB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,EACD,OAAO,GAAG,OAAO;IAEjB;wFACoF;IACpF,IAAI,EAAE,eAAe,CAAC;IACtB;mGAC+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE;QACR,WAAW,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QACpD,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,cAAc,EAAE,CACd,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,UAAU,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,EAC3C,MAAM,EAAE,WAAW,KAChB,UAAU,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAmGD,eAAO,MAAM,uBAAuB,EAA+C,CACjF,UAAU,SAAS;IACjB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,EACD,OAAO,GAAG,OAAO,EAEjB,KAAK,EAAE,4BAA4B,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAC,6BAA6B,CAAC,CAAA;CAAE,KACpG,KAAK,CAAC,YAAY,CAAC"}

package/dist/react/deferred-upload-form-shell.js

@@ -0,0 +1,56 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useRef, useCallback, useImperativeHandle, forwardRef, } from 'react';
+import { MediaInput } from '@ttt-productions/file-input/react';
+function DeferredUploadFormShellInner(props, ref) {
+    const { spec, originId: _originId, mutation, buildVariables, onSuccess, onError, onFileChange, children, } = props;
+    const [selectedFile, setSelectedFile] = useState(null);
+    const [uploadState, setUploadState] = useState(null);
+    const fileAreaRef = useRef(null);
+    const abortControllerRef = useRef(null);
+    const handleMediaChange = useCallback((payload) => {
+        const next = payload.error ? null : (payload.file ?? null);
+        setSelectedFile(next);
+        onFileChange?.(next);
+    }, [onFileChange]);
+    const handleClear = useCallback(() => {
+        setSelectedFile(null);
+        onFileChange?.(null);
+    }, [onFileChange]);
+    const handleCancel = useCallback(() => {
+        abortControllerRef.current?.abort();
+    }, []);
+    const handleSubmit = useCallback(async () => {
+        if (mutation.isPending)
+            return;
+        if (selectedFile) {
+            fileAreaRef.current?.focus();
+        }
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        try {
+            const result = await mutation.mutateAsync(buildVariables(selectedFile, setUploadState, controller.signal));
+            setUploadState(null);
+            setSelectedFile(null);
+            onFileChange?.(null);
+            onSuccess?.(result);
+        }
+        catch (err) {
+            setUploadState(null);
+            // User-initiated cancel: swallow the AbortError, reset selection, do not fire onError.
+            if (err instanceof Error && err.name === 'AbortError') {
+                setSelectedFile(null);
+                onFileChange?.(null);
+                return;
+            }
+            onError?.(err);
+        }
+        finally {
+            abortControllerRef.current = null;
+        }
+    }, [mutation, selectedFile, buildVariables, onSuccess, onError, onFileChange]);
+    useImperativeHandle(ref, () => ({ submit: () => { void handleSubmit(); } }), [handleSubmit]);
+    return (_jsxs(_Fragment, { children: [children, _jsx("div", { ref: fileAreaRef, tabIndex: -1, "aria-live": "polite", className: "outline-none", children: _jsx(MediaInput, { spec: spec, selectedFile: selectedFile, uploadState: uploadState, isLoading: mutation.isPending, disabled: mutation.isPending, onChange: handleMediaChange, onClear: handleClear, onCancel: handleCancel }) })] }));
+}
+export const DeferredUploadFormShell = forwardRef(DeferredUploadFormShellInner);
+//# sourceMappingURL=deferred-upload-form-shell.js.map

package/dist/react/deferred-upload-form-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-upload-form-shell.js","sourceRoot":"","sources":["../../src/react/deferred-upload-form-shell.tsx"],"names":[],"mappings":"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"}

package/dist/react/guarded-link.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Render-prop link wrapper that guards navigation when an upload is in
+ * progress. The consumer owns the actual navigator component (Next.js Link,
+ * React Router Link, plain anchor, etc.) — this wrapper only injects the
+ * onClick interceptor.
+ *
+ * Why render-prop and not `as={Link}`? Polymorphic `as` props create
+ * notoriously bad TypeScript inference and force the wrapper to forward all
+ * link-specific props. Render-prop keeps the consumer in full control of the
+ * link API, costs one extra wrapper closure, and keeps upload-ui agnostic of
+ * Next.js / React Router / etc.
+ *
+ * Design note: the design spec lists `<GuardedNavigationButton>` as a second
+ * component. We deliberately don't ship it — buttons that navigate use
+ * `useGuardedNavigation()` directly in one line. A second component would
+ * split the same surface for no payoff.
+ *
+ * Usage:
+ *
+ *     <GuardedLink renderLink={({ onClick, children }) => (
+ *       <Link href="/your/destination" onClick={onClick}>{children}</Link>
+ *     )}>
+ *       View all uploads →
+ *     </GuardedLink>
+ */
+import type { MouseEvent, ReactNode } from 'react';
+export interface GuardedLinkRenderArgs {
+    /** Click handler the consumer MUST attach to its underlying link element. */
+    onClick: (event: MouseEvent<HTMLElement>) => void;
+    /** The children passed to `<GuardedLink>` — forward them to the link. */
+    children: ReactNode;
+}
+export interface GuardedLinkProps {
+    children: ReactNode;
+    renderLink: (args: GuardedLinkRenderArgs) => ReactNode;
+}
+export declare function GuardedLink(props: GuardedLinkProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=guarded-link.d.ts.map

package/dist/react/guarded-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-link.d.ts","sourceRoot":"","sources":["../../src/react/guarded-link.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGnD,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,yEAAyE;IACzE,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB,UAAU,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,SAAS,CAAC;CACxD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,2CAWlD"}

package/dist/react/guarded-link.js

@@ -0,0 +1,14 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useLocalUploadGuard } from './local-upload-guard-provider.js';
+export function GuardedLink(props) {
+    const { children, renderLink } = props;
+    const { confirmNavigation } = useLocalUploadGuard();
+    const onClick = (event) => {
+        if (!confirmNavigation()) {
+            event.preventDefault();
+        }
+    };
+    return _jsx(_Fragment, { children: renderLink({ onClick, children }) });
+}
+//# sourceMappingURL=guarded-link.js.map

package/dist/react/guarded-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-link.js","sourceRoot":"","sources":["../../src/react/guarded-link.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AA6Bb,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAcvE,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IACvC,MAAM,EAAE,iBAAiB,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAEpD,MAAM,OAAO,GAAG,CAAC,KAA8B,EAAE,EAAE;QACjD,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;YACzB,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,4BAAG,UAAU,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAI,CAAC;AAClD,CAAC"}

package/dist/react/in-flight-uploads-provider.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Generic in-flight uploads provider.
+ *
+ * Provides a global Map of in-flight upload state by `pendingMediaId`, derived
+ * from a Firestore listener over the consumer-supplied collection. On terminal
+ * status transitions observed THIS SESSION, fires consumer-supplied success /
+ * failure / rejection callbacks. Records monitoring breadcrumbs and parse
+ * errors through the injected monitoring callback.
+ *
+ * EVERY TTT-specific value is supplied by the consumer:
+ *  - userId resolution
+ *  - Firestore `db` reference
+ *  - collection path
+ *  - listener time window (ms)
+ *  - parser/schema for raw Firestore doc → typed PendingMedia
+ *  - success copy per origin
+ *  - notification callback (cache invalidation, etc.)
+ *  - toast callback
+ *  - rejection callback (for the media-rejection dialog or equivalent)
+ *  - monitoring callback (breadcrumbs + captured errors)
+ *
+ * Read APIs:
+ *  - `useInFlightUploadsState()` — full Map.
+ *  - `useInFlightUpload(id)` — single doc, narrowable on status.
+ *  - `useUploadActivityState()` — tray-visible items, sorted newest-first.
+ *
+ * The package owns the deduplication, initial-snapshot suppression, and
+ * non-terminal → terminal transition tracking. It does NOT own anything about
+ * what a file-origin is or what message text appears in toasts.
+ */
+import { type ReactNode } from 'react';
+/**
+ * Generic pending-media status. Identical to TTT's PendingMedia status union,
+ * but defined here so upload-ui has no ttt-core dependency.
+ */
+export type InFlightUploadStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'rejected';
+/**
+ * Generic in-flight upload record. The provider keeps a Map<id, InFlightUpload>
+ * built from each parsed PendingMedia. Consumers parameterize the `fileOrigin`
+ * type via the parser's return type (the provider treats it as opaque).
+ *
+ * `TFileOrigin` defaults to `string` so unannotated consumers get a permissive
+ * shape; ttt-prod will bind it to its `FileOrigin` union at the call site.
+ */
+export type InFlightUploadBase<TFileOrigin extends string = string> = {
+    id: string;
+    fileOrigin: TFileOrigin;
+    surface: string;
+    createdAt: number;
+    targetIds?: string[];
+};
+export type InFlightUploadActive<TFileOrigin extends string = string> = InFlightUploadBase<TFileOrigin> & {
+    status: 'pending' | 'processing';
+};
+export type InFlightUploadCompleted<TFileOrigin extends string = string> = InFlightUploadBase<TFileOrigin> & {
+    status: 'completed';
+    completedAt: number;
+    uploadTrayClearedAt?: number;
+    uploadTrayClearedBy?: string;
+};
+export type InFlightUploadFailed<TFileOrigin extends string = string> = InFlightUploadBase<TFileOrigin> & {
+    status: 'failed';
+    failedAt: number;
+    errorCategory: string;
+    errorMessage: string;
+    uploadTrayClearedAt?: number;
+    uploadTrayClearedBy?: string;
+};
+export type InFlightUploadRejected<TFileOrigin extends string = string> = InFlightUploadBase<TFileOrigin> & {
+    status: 'rejected';
+    rejectedAt: number;
+    rejectionType: 'text' | 'media';
+    errorMessage: string;
+    violationId?: string;
+    uploadTrayClearedAt?: number;
+    uploadTrayClearedBy?: string;
+};
+export type InFlightUpload<TFileOrigin extends string = string> = InFlightUploadActive<TFileOrigin> | InFlightUploadCompleted<TFileOrigin> | InFlightUploadFailed<TFileOrigin> | InFlightUploadRejected<TFileOrigin>;
+/**
+ * Result of the consumer-supplied parser. The provider keeps the raw parsed
+ * record for callbacks (so consumers can read domain events, target IDs, etc.)
+ * AND derives the generic InFlightUpload from it for the public Map.
+ *
+ * The parser MUST throw if validation fails; the provider catches and routes
+ * the error to the monitoring callback.
+ */
+export type ParsedPendingMedia<TFileOrigin extends string = string> = {
+    id: string;
+    userId: string;
+    fileOrigin: TFileOrigin;
+    status: InFlightUploadStatus;
+    createdAt: number;
+    surface: string;
+    targetIds?: string[];
+    completedAt?: number;
+    failedAt?: number;
+    rejectedAt?: number;
+    errorCategory?: string;
+    errorMessage?: string;
+    rejectionType?: 'text' | 'media';
+    violationId?: string;
+    uploadTrayClearedAt?: number;
+    uploadTrayClearedBy?: string;
+    /**
+     * Opaque consumer-controlled domain-event payload, surfaced to the
+     * `onUploadCompleted` and `onUploadRejected` callbacks for cache
+     * invalidation. The provider does not interpret it.
+     */
+    domainEvents?: unknown;
+};
+export type InFlightUploadsAdapter<TFileOrigin extends string = string> = {
+    /** Returns the current user's uid, or null if not signed in. */
+    getCurrentUserId: () => string | null;
+    /** Firestore database adapter (loose typing — `unknown` keeps zero firebase coupling at the type level). */
+    db: unknown;
+    /** Collection path holding pending-media docs (e.g. "pendingMedia"). */
+    collectionPath: string;
+    /** Listener window in milliseconds — only docs with `createdAt >= now - window` are tracked. */
+    listenerWindowMs: number;
+    /**
+     * Parse a raw Firestore doc snapshot's `.data()` into the generic shape the
+     * provider tracks. Throws on validation failure; the provider routes thrown
+     * errors to `onMonitoringEvent`.
+     */
+    parsePendingMedia: (raw: unknown) => ParsedPendingMedia<TFileOrigin>;
+    /** Called once per observed non-terminal → terminal completed transition. */
+    onUploadCompleted: (parsed: ParsedPendingMedia<TFileOrigin>) => void;
+    /** Called once per observed non-terminal → terminal failed transition. */
+    onUploadFailed: (parsed: ParsedPendingMedia<TFileOrigin>) => void;
+    /** Called once per observed non-terminal → terminal rejected transition. */
+    onUploadRejected: (parsed: ParsedPendingMedia<TFileOrigin>) => void;
+    /**
+     * Monitoring callback. Receives:
+     *  - `breadcrumb`: informational, fired on every observed terminal transition.
+     *  - `parse-error`: when `parsePendingMedia` throws.
+     *  - `listener-error`: when the Firestore listener's error callback fires.
+     *
+     * Consumers wire this to Sentry, OpenTelemetry, or any other observability
+     * provider. The provider does NOT import any monitoring SDK directly.
+     */
+    onMonitoringEvent: (event: InFlightUploadsMonitoringEvent<TFileOrigin>) => void;
+};
+export type InFlightUploadsMonitoringEvent<TFileOrigin extends string = string> = {
+    type: 'breadcrumb';
+    category: 'upload.terminal';
+    level: 'info';
+    message: string;
+    data: {
+        id: string;
+        fileOrigin: TFileOrigin;
+        status: InFlightUploadStatus;
+        surface: string;
+    };
+} | {
+    type: 'parse-error';
+    docId: string;
+    error: unknown;
+    data: unknown;
+} | {
+    type: 'listener-error';
+    error: unknown;
+};
+/**
+ * Minimal subscription contract used by the provider. The default
+ * implementation lives in `firestore-subscribe.ts` and uses the standard
+ * `firebase/firestore` `onSnapshot` + `query` + `where` builders.
+ *
+ * Tests inject a fake to drive the listener without spinning up Firestore.
+ */
+export type FirestoreSubscribeFn = (args: {
+    db: unknown;
+    collectionPath: string;
+    userId: string;
+    windowStartMs: number;
+    onSnapshot: (snapshot: FirestoreLikeSnapshot) => void;
+    onError: (error: unknown) => void;
+}) => () => void;
+export type FirestoreLikeSnapshot = {
+    docChanges: () => FirestoreLikeDocChange[];
+};
+export type FirestoreLikeDocChange = {
+    type: 'added' | 'modified' | 'removed';
+    doc: {
+        id: string;
+        data: () => unknown;
+    };
+};
+export interface InFlightUploadsProviderProps<TFileOrigin extends string = string> {
+    adapter: InFlightUploadsAdapter<TFileOrigin>;
+    /** Firestore subscription function. Defaults to the firebase/firestore implementation. */
+    subscribe?: FirestoreSubscribeFn;
+    children: ReactNode;
+}
+export declare function InFlightUploadsProvider<TFileOrigin extends string = string>(props: InFlightUploadsProviderProps<TFileOrigin>): import("react/jsx-runtime").JSX.Element;
+export declare function useInFlightUploadsState<TFileOrigin extends string = string>(): Map<string, InFlightUpload<TFileOrigin>>;
+export declare function useInFlightUpload<TFileOrigin extends string = string>(id: string | null | undefined): InFlightUpload<TFileOrigin> | undefined;
+/**
+ * `true` for `completed` / `failed` / `rejected`. Used by tray UI to decide
+ * whether a Clear action is available for an item.
+ */
+export declare function isTerminalUpload<TFileOrigin extends string = string>(item: InFlightUpload<TFileOrigin>): item is Exclude<InFlightUpload<TFileOrigin>, {
+    status: 'pending' | 'processing';
+}>;
+/**
+ * Tray-visible items. Includes every pending/processing upload, plus terminal
+ * uploads that have NOT been cleared from the tray. Sorted newest-first by
+ * createdAt.
+ *
+ * Renamed per F22: was `useUploadActivityTrayItems` in ttt-prod; the public
+ * selector name in upload-ui is `useUploadActivityState`. The mutation hook
+ * is `useClearUploadActivity` (in a separate file).
+ */
+export declare function useUploadActivityState<TFileOrigin extends string = string>(): InFlightUpload<TFileOrigin>[];
+//# sourceMappingURL=in-flight-uploads-provider.d.ts.map

package/dist/react/in-flight-uploads-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-flight-uploads-provider.d.ts","sourceRoot":"","sources":["../../src/react/in-flight-uploads-provider.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAMf;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,UAAU,CAAC;AAEf;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAAI;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,WAAW,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAClE,kBAAkB,CAAC,WAAW,CAAC,GAAG;IAChC,MAAM,EAAE,SAAS,GAAG,YAAY,CAAC;CAClC,CAAC;AAEJ,MAAM,MAAM,uBAAuB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IACrE,kBAAkB,CAAC,WAAW,CAAC,GAAG;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEJ,MAAM,MAAM,oBAAoB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAClE,kBAAkB,CAAC,WAAW,CAAC,GAAG;IAChC,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEJ,MAAM,MAAM,sBAAsB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IACpE,kBAAkB,CAAC,WAAW,CAAC,GAAG;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEJ,MAAM,MAAM,cAAc,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAC1D,oBAAoB,CAAC,WAAW,CAAC,GACjC,uBAAuB,CAAC,WAAW,CAAC,GACpC,oBAAoB,CAAC,WAAW,CAAC,GACjC,sBAAsB,CAAC,WAAW,CAAC,CAAC;AAMxC;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAAI;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,WAAW,CAAC;IACxB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAAI;IACxE,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAEtC,4GAA4G;IAC5G,EAAE,EAAE,OAAO,CAAC;IAEZ,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IAEvB,gGAAgG;IAChG,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAErE,6EAA6E;IAC7E,iBAAiB,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAErE,0EAA0E;IAC1E,cAAc,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAElE,4EAA4E;IAC5E,gBAAgB,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAEpE;;;;;;;;OAQG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,8BAA8B,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACjF,CAAC;AAEF,MAAM,MAAM,8BAA8B,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAC1E;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,UAAU,EAAE,WAAW,CAAC;QACxB,MAAM,EAAE,oBAAoB,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAMN;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE;IACxC,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACtD,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC,KAAK,MAAM,IAAI,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,MAAM,sBAAsB,EAAE,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACvC,GAAG,EAAE;QACH,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AAYF,MAAM,WAAW,4BAA4B,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM;IAC/E,OAAO,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAC7C,0FAA0F;IAC1F,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAgDD,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,EACzE,KAAK,EAAE,4BAA4B,CAAC,WAAW,CAAC,2CAgKjD;AAMD,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,KAAK,GAAG,CACjF,MAAM,EACN,cAAc,CAAC,WAAW,CAAC,CAC5B,CAMA;AAED,wBAAgB,iBAAiB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,EACnE,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC5B,cAAc,CAAC,WAAW,CAAC,GAAG,SAAS,CAOzC;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,EAClE,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,GAChC,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE;IAAE,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;CAAE,CAAC,CAMpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,KAAK,cAAc,CAAC,WAAW,CAAC,EAAE,CAU3G"}