@drawbridge/components 0.0.78 → 0.1.1

package/types/dashboard/lib/hooks.d.ts

@@ -0,0 +1,65 @@
+import { Dispatch, SetStateAction } from 'react';
+import { QueryClient, QueryFilters } from '@tanstack/react-query';
+
+export interface SortingItem {
+	desc: boolean;
+	id: string;
+}
+
+export declare const useCopyToClipboard: ( props?: { onClick?: () => void; value?: string } ) => {
+	copied: boolean;
+	onCopy: () => void;
+};
+
+export declare const useCallbacks: ( props: {
+	query?: { refetch?: ( response: unknown ) => unknown };
+	queryClient: QueryClient;
+} ) => {
+	onError: ( response: unknown ) => void;
+	onSuccess: ( response: unknown, options?: { invalidate?: unknown[]; redirect?: string } ) => Promise<void>;
+	// A save that changes the screen before the api answers (an optimistic
+	// reorder). Returns the chain's queue promise, which resolves once this
+	// save (and every save queued ahead of it) has settled.
+	optimistic: ( props: {
+		filters: QueryFilters;
+		save: () => Promise<unknown>;
+		update: ( data: unknown ) => unknown;
+	} ) => Promise<void>;
+};
+
+export declare const useDrawer: ( props: { queryClient: QueryClient } ) => {
+	close: () => void;
+	open: ( props?: Record<string, unknown> ) => void;
+};
+
+export declare const useSort: (
+	props: { sort?: Record<string, 1 | -1>; onChange?: () => void },
+	options?: { param?: string }
+) => {
+	manualSorting: true;
+	onSortingChange: Dispatch<SetStateAction<SortingItem[]>>;
+	sort: Record<string, 1 | -1> | undefined;
+	sorting: SortingItem[];
+};
+
+export declare const useUrlFilterState: <T>(
+	defaults: T,
+	options?: { param?: string }
+) => [ T, ( next: T | ( ( current: T ) => T ) ) => void, () => void ];
+
+export declare const useModal: ( props: { queryClient: QueryClient } ) => {
+	close: () => void;
+	open: ( props?: Record<string, unknown> ) => void;
+};
+
+// Shared socket-room lifecycle for the TemplateSocket* components. Re-emits
+// `join.<room>` and invalidates `resync`'s queries on every connect and
+// reconnect, since socket.io does not replay room emits made while
+// disconnected.
+export declare const useSocketRoom: ( props: {
+	arg?: unknown;
+	enabled: boolean;
+	listeners: Record<string, ( ...payload: unknown[] ) => void>;
+	resync?: unknown[][];
+	room: string;
+} ) => void;

package/types/dashboard/lib/navigation.d.ts

@@ -0,0 +1,24 @@
+// Decide whether a document-level click would soft-navigate the app, mirroring
+// next/link's own exclusion list (modified clicks, downloads, new tabs,
+// external urls, hash-only movement). Returns the in-app destination to
+// navigate to after confirmation, or null when the click must pass through.
+export declare const interceptHref: ( props: {
+	anchor?: {
+		download?: unknown;
+		href?: string;
+		target?: string;
+	};
+	event?: {
+		altKey?: boolean;
+		button?: number;
+		ctrlKey?: boolean;
+		metaKey?: boolean;
+		shiftKey?: boolean;
+	};
+	location: {
+		href: string;
+		origin: string;
+		pathname: string;
+		search: string;
+	};
+} ) => string | null;

package/types/dashboard/lib/otc.d.ts

@@ -0,0 +1,10 @@
+// The one place that asks the api to dispatch a sign-in / sign-up code.
+// Throws when the api's response carries no otcId — a malformed address and
+// an internal error are both shaped like success, so the client advances only
+// when there is actually a code on the way.
+export declare const requestOtc: ( props: {
+	action: string;
+	body?: Record<string, unknown>;
+	endpoint: string;
+	executeRecaptcha?: ( ( action: string ) => Promise<string> ) | undefined;
+} ) => Promise<string>;

package/types/dashboard/lib/overage.d.ts

@@ -0,0 +1,9 @@
+// The custom-plan overage rate: stored as cents per action, edited in
+// dollars. Non-finite in, non-value out.
+
+// cents -> the dollar string the form renders ('' when `cents` isn't finite).
+export declare const overageToForm: ( cents: number | null | undefined ) => number | '';
+
+// dollars -> the cents integer the PUT body carries (undefined, so the key is
+// omitted, when `dollars` isn't finite).
+export declare const overageFromForm: ( dollars: number | null | undefined ) => number | undefined;

package/types/dashboard/lib/table-actions.d.ts

@@ -0,0 +1,18 @@
+import { TableActions } from '../table';
+
+// An organization row's action: Upgrade, Update terms, Suspended or Select
+// (a plain anchor to /api/switch/:id, never a prefetching Link).
+export declare const organizationAction: ( props: {
+	onClickSuspended?: () => void;
+	onClickTerms?: () => void;
+	onClickUpgrade?: () => void;
+	record: {
+		access?: string;
+		id: string;
+		status?: string;
+		terms?: { valid?: boolean };
+		version?: { valid?: boolean };
+		[ key: string ]: unknown;
+	};
+	redirectTo?: string;
+} ) => TableActions;

package/types/dashboard/lib/time-slots.d.ts

@@ -0,0 +1,34 @@
+// Slot maths for the 12-hour time picker (components/input-time.js).
+
+export type Period = 'AM' | 'PM';
+
+export interface TimeSlot {
+	hour: string;
+	minute: string;
+	second?: string;
+	period: Period;
+}
+
+export declare const HOURS: string[];
+
+export declare const MINUTES: string[];
+
+export declare const PERIODS: Period[];
+
+// Compose a Date on `date` from a 12h { hour, minute, period } slot.
+export declare const compose: ( date: Date, slot: Pick<TimeSlot, 'hour' | 'minute' | 'period'> ) => Date;
+
+// A slot is past when the latest time it can still reach (on the selected
+// day, relative to `min`) is already before `min`. Only applies for a
+// same-day `min` — future days disable nothing.
+export declare const isPastSlot: ( props: {
+	candidate: Partial<Pick<TimeSlot, 'hour' | 'minute' | 'period'>>;
+	date: Date | null | undefined;
+	granularity: 'hour' | 'minute' | 'period';
+	min: Date | null | undefined;
+	value: Pick<TimeSlot, 'hour' | 'period'>;
+} ) => boolean;
+
+// The 12h slot a Date sits in. `null`/`undefined` yields the midnight
+// default.
+export declare const toTimeSlot: ( date?: Date | null ) => TimeSlot;

package/types/dashboard/lib/trickle.d.ts

@@ -0,0 +1,11 @@
+// The upload bar's "always moving" step: the displayed percentage eases
+// toward `real` progress each tick rather than mirroring it, capped at 99
+// until the transfer settles.
+export declare const trickle: ( props?: {
+	displayed?: number;
+	real?: number;
+	headroom?: number;
+	maximum?: number;
+	minimum?: number;
+	rate?: number;
+} ) => number;

package/types/dashboard/lib/uppy.d.ts

@@ -0,0 +1,36 @@
+// Presigned S3 multipart transport for large uploads, built on a headless
+// Uppy instance held at module scope (it has to survive the uploader
+// component unmounting on a tab switch or modal close).
+
+// An Uppy instance, typed loosely to the surface this module actually reads —
+// the real type lives in @uppy/core, which this package does not depend on
+// directly (it is dynamically imported inside uppy.js).
+export interface UppyInstance {
+	destroy: () => void;
+	getFiles: () => Array<{
+		progress?: {
+			uploadComplete?: boolean;
+			uploadStarted?: boolean;
+		};
+	}>;
+	[ key: string ]: unknown;
+}
+
+// Mirrors the api's chunking: the number of bytes per multipart part for a
+// file of this size.
+export declare const partSizeFor: ( bytes: number ) => number;
+
+export declare const isUploading: ( uploader: UppyInstance | null | undefined ) => boolean;
+
+// Returns the module-scoped uploader, creating one (or replacing the current
+// one, if its restrictions differ) when none matches `endpoint` + `type` +
+// `maxFileSize`.
+export declare const getUploader: ( props: {
+	endpoint: string;
+	maxFileSize?: number;
+	type?: string;
+} ) => Promise<UppyInstance>;
+
+// Tears down the module-scoped uploader — a no-op while a transfer is still
+// in flight, since destroy() would cancel it.
+export declare const releaseUploader: () => void;

package/types/dashboard/lib/utm.d.ts

@@ -0,0 +1,32 @@
+// The campaign a visitor arrived on, read off the auth page's own query
+// string. Deliberately not a validator — it forwards known keys, and the api
+// is the one allow-list that decides what is real.
+
+export interface Click {
+	fbclid?: string;
+	gclid?: string;
+	liFatId?: string;
+	msclkid?: string;
+	ttclid?: string;
+}
+
+export interface Utm {
+	campaign?: string;
+	content?: string;
+	id?: string;
+	medium?: string;
+	source?: string;
+	term?: string;
+	click?: Click;
+}
+
+export type SearchParams = Record<string, string | string[] | undefined>;
+
+// From a Next.js searchParams object, where a repeated parameter arrives as
+// an array — dropped rather than resolved, to avoid inventing a value. Null
+// when nothing recognized was present.
+export declare const utmFromParams: ( params: SearchParams | null | undefined ) => Utm | null;
+
+// The same values as flat query parameters, for the Google flow's authorize
+// request.
+export declare const utmToQuery: ( utm: Utm | null | undefined ) => Record<string, string>;

package/types/dashboard/link-back.d.ts

@@ -0,0 +1,15 @@
+import { ComponentType, ElementType, ReactNode, SVGProps } from 'react';
+
+// A link-variant Button with the back arrow first; a long label truncates to one line.
+export interface LinkBackProps {
+	children?: ReactNode;
+	// Link by default; 'button' for a back step inside a drawer.
+	element?: ElementType;
+	icon?: ComponentType<SVGProps<SVGSVGElement>>;
+	// Spread onto the Button ( href, onClick, aria-label, size 'small' for a drawer's text-sm Back… ).
+	[ key: string ]: unknown;
+}
+
+declare const LinkBack: ComponentType<LinkBackProps>;
+
+export default LinkBack;

package/types/dashboard/link.d.ts

@@ -0,0 +1,17 @@
+import { ComponentProps, ComponentType } from 'react';
+import NextLink from 'next/link';
+
+// next/link with prefetch defaulting to false: a dashboard link loads when it
+// is clicked. Every other next/link and anchor prop passes through.
+export type LinkProps = ComponentProps<typeof NextLink>;
+
+// The page-wide progress bar every waiting Link reports to; mount it once in
+// the root layout. Renders nothing until a click has waited 500ms.
+export const LinkProgress: ComponentType;
+
+// One tick of the bar: the next width ( 0–100 ) from the current one.
+export function step( state: { busy: boolean; displayed: number; waited?: number } ): number;
+
+declare const Link: ComponentType<LinkProps>;
+
+export default Link;

package/types/dashboard/list-resource.d.ts

@@ -0,0 +1,39 @@
+import { ComponentType, ReactNode } from 'react';
+
+export interface ListResourceItem {
+	id: string;
+	title?: string;
+	[ key: string ]: unknown;
+}
+
+export interface ListResourceButton {
+	button: {
+		// Button props: spread them onto a Button.
+		props: { inline: true; onClick: () => Promise<void>; size: 'small' };
+		text: string;
+	};
+	item: ListResourceItem;
+}
+
+export interface ListResourceProps {
+	// Replaces "No <model>s found".
+	empty?: ReactNode;
+	// A paged GET list ( { items, pageInfo } ).
+	endpoint: string;
+	// Singular noun for the empty message.
+	model: string;
+	// false keeps selected rows listed ( a single-select picker ).
+	multiple?: boolean;
+	// Without it the rows have no Add button.
+	onChange?: ( item: ListResourceItem ) => unknown;
+	params?: Record<string, unknown>;
+	render?: ( item: ListResourceItem ) => ReactNode;
+	renderButton?: ( args: ListResourceButton ) => ReactNode;
+	searchKeys?: string[];
+	// Left out of the list when multiple.
+	selected?: ListResourceItem[];
+}
+
+declare const ListResource: ComponentType<ListResourceProps>;
+
+export default ListResource;

package/types/dashboard/list.d.ts

@@ -0,0 +1,26 @@
+import { ComponentType, ElementType, ReactNode, SVGProps } from 'react';
+
+export interface ListItem {
+	// Accepted and ignored.
+	complete?: unknown;
+	// Rendered as a <p> unless href is set; the current page's href stays plain.
+	element?: ElementType;
+	href?: string;
+	icon?: ComponentType<SVGProps<SVGSVGElement>>;
+	// Accepted and ignored.
+	increment?: unknown;
+	title: ReactNode;
+	// Spread onto the row.
+	[ key: string ]: unknown;
+}
+
+export interface ListProps {
+	className?: string;
+	items?: ListItem[];
+	// Show the trailing arrow ( or the item's icon ).
+	svg?: boolean;
+}
+
+declare const List: ComponentType<ListProps>;
+
+export default List;

package/types/dashboard/menu.d.ts

@@ -0,0 +1,65 @@
+import { ComponentType, ElementType, MouseEventHandler, ReactNode } from 'react';
+
+// One row of a GET /menu/* group ( drawbridge-api lib/menus.js ).
+export interface MenuItem {
+	badge?: { text?: ReactNode; type?: string };
+	description?: string;
+	disabled?: boolean;
+	element?: ElementType;
+	// Shows the warning dot.
+	error?: boolean;
+	// Active only on an exact path match.
+	exact?: boolean;
+	// Without href the row is inert.
+	href?: string;
+	key?: string;
+	locked?: boolean;
+	title: ReactNode;
+	total?: number;
+	[ key: string ]: unknown;
+}
+
+export interface MenuGroup {
+	items: MenuItem[];
+	title?: string;
+}
+
+interface MenuSidebarProps {
+	onClick?: MouseEventHandler;
+	// The current pathname, which picks the active row.
+	path: string;
+}
+
+export interface MenuOrganizationProps extends MenuSidebarProps {
+	organization: string;
+}
+
+export interface MenuCampaignProps extends MenuOrganizationProps {
+	campaign: string;
+}
+
+export interface MenuAccountDropdownProps {
+	// The [ 'account' ] query.
+	account?: { data?: { email?: string; firstName?: string; lastName?: string; permissions?: string[]; status?: string; totals?: { inbox?: number }; [ key: string ]: unknown } };
+	actions: { guide?: () => void; signout: () => void };
+	// The [ 'account', 'balance' ] query; ai in cents.
+	balance?: { data?: { ai?: number } };
+	// Truthy adds the Screen guide entry.
+	guide?: unknown;
+	// The useModal() pair; the processing list opens in it.
+	modal: { close: () => void; open: ( props: { message?: ReactNode; title?: ReactNode } ) => void };
+	onClick?: MouseEventHandler;
+}
+
+// GET /menu/organization/:organization
+export const MenuOrganization: ComponentType<MenuOrganizationProps>;
+// GET /menu/organization/:organization/campaign/:campaign
+export const MenuCampaign: ComponentType<MenuCampaignProps>;
+// GET /menu/admin
+export const MenuAdmin: ComponentType<MenuSidebarProps>;
+// GET /menu/account
+export const MenuAccount: ComponentType<MenuSidebarProps>;
+// My organizations and Shared with me; no request.
+export const MenuApp: ComponentType<MenuSidebarProps>;
+// The account row at the foot of the sidebar; reads GET /account/process.
+export const MenuAccountDropdown: ComponentType<MenuAccountDropdownProps>;

package/types/dashboard/modal.d.ts

@@ -0,0 +1,20 @@
+import { ComponentType, ReactNode } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+
+export interface ModalProps {
+	active?: boolean;
+	// Stacking classes for the overlay and dialog; defaults to 'z-50'.
+	className?: string;
+	// Rendered inside FormScope 'modal', so GuardNavigation tracks its forms.
+	message?: ReactNode;
+	// Without it the close button clears the shared [ 'modal' ] query (and is guarded).
+	onClose?: () => void;
+	// Needed for the shared close when onClose is not given.
+	queryClient: QueryClient;
+	// Without a title there is no header or close button.
+	title?: ReactNode;
+}
+
+declare const Modal: ComponentType<ModalProps>;
+
+export default Modal;

package/types/dashboard/notes.d.ts

@@ -0,0 +1,20 @@
+import { ComponentType } from 'react';
+
+export interface NotesProps {
+	// The base the notes live under: '' for an organization, '/admin' on admin pages.
+	// Lists GET {endpoint}/notes, saves POST {endpoint}/note.
+	endpoint?: string;
+	// Sent as the list's filters, e.g. { 'meta.organization': id, 'meta.invoice': id }.
+	filters?: Record<string, unknown>;
+	limit?: number;
+	// False hides Add note and each note's delete.
+	manage?: boolean;
+	// Stored on a new note.
+	meta?: Record<string, unknown>;
+	// A new note's type, e.g. 'public' on a draw.
+	type?: string;
+}
+
+declare const Notes: ComponentType<NotesProps>;
+
+export default Notes;

package/types/dashboard/notice.d.ts

@@ -0,0 +1,20 @@
+import { ComponentType } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+
+export interface NoticeResponse {
+	button?: { href: string; text: string };
+	message?: string;
+	[ key: string ]: unknown;
+}
+
+export interface NoticeProps {
+	active?: boolean;
+	// Closing (and the three-second timeout) writes active : false to [ 'notice' ].
+	queryClient: QueryClient;
+	// An Error reads in red and stays until closed; anything else leaves after 3s.
+	response?: NoticeResponse | Error | null;
+}
+
+declare const Notice: ComponentType<NoticeProps>;
+
+export default Notice;

package/types/dashboard/paged.d.ts

@@ -0,0 +1,57 @@
+import { ElementType, ReactNode } from 'react';
+import { QueryKey } from '@tanstack/react-query';
+
+export interface PagedPageInfo {
+	endCursor?: string | null;
+	hasNextPage?: boolean;
+	hasPreviousPage?: boolean;
+	total?: number;
+}
+
+export interface PagedEmptyContext {
+	// The api's `empty` for this list, or the failed-load message.
+	empty?: { message?: string; [ key: string ]: unknown };
+	error?: Error & { status?: number };
+	// A 403 (or the api's `locked`): the reason the list can't be read.
+	locked?: { message?: string; [ key: string ]: unknown };
+}
+
+export interface PagedEmpty {
+	cta?: ReactNode;
+	message?: ReactNode;
+	// Empty's background: 'primary' white, 'secondary' light grey; transparent otherwise.
+	variant?: 'primary' | 'secondary';
+}
+
+export interface PagedChildrenContext<TItem = any> {
+	items: TItem[];
+	pageInfo?: PagedPageInfo;
+	// Renders the pagination row elsewhere (pass pagination={ false } to hide the default).
+	pagination: ( options: { className?: string | null; counter?: ReactNode } ) => ReactNode;
+}
+
+export interface PagedProps<TItem = any> {
+	children?: ( context: PagedChildrenContext<TItem> ) => ReactNode;
+	className?: string;
+	classNameInner?: string;
+	classNamePagination?: string;
+	element?: ElementType;
+	empty?: PagedEmpty | ( ( context: PagedEmptyContext ) => ReactNode );
+	endpoint: string;
+	// Defaults to WrapperGradient.
+	innerElement?: ElementType;
+	pagination?: boolean;
+	// Sent with the request; `limit` defaults to 12, `sort` to { createdAt: -1 }.
+	params?: { limit?: number; sort?: Record<string, 1 | -1>; search?: unknown; filters?: Record<string, unknown>; [ key: string ]: unknown };
+	// Mirrors page / cursor into the URL and drops empty params from the request.
+	queryParams?: boolean;
+	queryKey?: QueryKey;
+	render?: ( item: TItem, index: number ) => ReactNode;
+	// The starting page when queryParams is off or the URL carries none.
+	skip?: number;
+	[ key: string ]: unknown;
+}
+
+declare const Paged: <TItem = any>( props: PagedProps<TItem> ) => ReactNode;
+
+export default Paged;

package/types/dashboard/provider-resource.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+import { QueryKey, UseQueryResult } from '@tanstack/react-query';
+
+export interface ProviderResourceProps<TData = any> {
+	// Passed to request().
+	cache?: RequestCache;
+	children?: ReactNode | ( ( query: UseQueryResult<TData> ) => ReactNode );
+	classNameLoader?: string;
+	// What the query resolves to when there is no endpoint.
+	data?: TData;
+	enabled?: boolean;
+	// GETs this and caches `result` under queryKey.
+	endpoint?: string;
+	// Shown when the request fails and nothing is cached. Without it a 429, 5xx
+	// or network failure offers a reload and any other failure calls notFound().
+	error?: ReactNode | ( ( query: UseQueryResult<TData> ) => ReactNode );
+	// Shows a spinner while loading; otherwise nothing renders until loaded.
+	loader?: boolean;
+	// Sent as the request's query string.
+	params?: Record<string, unknown>;
+	queryKey: QueryKey;
+	// Any other useQuery option ( and `token`, which the layouts pass ) is spread
+	// into useQuery.
+	[ key: string ]: unknown;
+}
+
+declare const ProviderResource: <TData = any>( props: ProviderResourceProps<TData> ) => ReactNode;
+
+export default ProviderResource;

package/types/dashboard/provider-ui.d.ts

@@ -0,0 +1,17 @@
+import { ComponentType, ReactNode } from 'react';
+
+export interface ProviderUiProps {
+	children?: ReactNode;
+	// The session token. Without it the account queries stay off (public routes)
+	// and requests go unauthenticated; with it, request() attaches it and the
+	// socket ( when NEXT_PUBLIC_SOCKET_URI is set ) authenticates with it.
+	token?: string | null;
+}
+
+// Must sit inside a QueryClientProvider ( Provider ). Loads [ 'account' ],
+// [ 'app' ], [ 'countries' ], [ 'currencies' ] and [ 'account', 'balance' ];
+// renders the shared Drawer, Modal and Notice from [ 'drawer' ], [ 'modal' ]
+// and [ 'notice' ] ( opened through useDrawer, useModal and useCallbacks ).
+declare const ProviderUi: ComponentType<ProviderUiProps>;
+
+export default ProviderUi;

package/types/dashboard/provider.d.ts

@@ -0,0 +1,12 @@
+import { ComponentType, ReactNode } from 'react';
+
+export interface ProviderProps {
+	children?: ReactNode;
+}
+
+// The dashboard's QueryClientProvider: no retries, no refetch on focus or
+// reconnect, staleTime Infinity. Adds the react-query devtools when
+// NEXT_PUBLIC_DEBUG is set.
+declare const Provider: ComponentType<ProviderProps>;
+
+export default Provider;

package/types/dashboard/recharts.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+
+export type ChartDataset =
+	| 'actions' | 'affiliates' | 'brands' | 'campaigns' | 'connections' | 'count' | 'discount'
+	| 'entries' | 'events' | 'fee' | 'files' | 'gross' | 'members' | 'net' | 'orders' | 'pages'
+	| 'pageviews' | 'qrcodes' | 'shortcodes' | 'storage' | 'workflows';
+
+// Spread onto the empty state shown in place of the chart.
+export interface ChartEmptyProps {
+	// Defaults to 'No data to display'.
+	message?: ReactNode;
+}
+
+export interface ChartBarProps {
+	data?: { name: string; value: number }[] | null;
+	empty?: ChartEmptyProps;
+}
+
+export interface ChartLineProps {
+	// One point per `date`, a number per dataset key.
+	data?: ( { date: string } & Partial<Record<ChartDataset, number>> )[] | null;
+	// Defaults to [ 'events', 'pageviews', 'qrcodes', 'shortcodes' ]. Shown empty
+	// when every point is zero across these.
+	datasets?: ChartDataset[];
+	empty?: ChartEmptyProps;
+	// Clicking an entry toggles its series.
+	legend?: boolean;
+}
+
+export declare const ChartBar: ( props: ChartBarProps ) => ReactNode;
+
+export declare const ChartLine: ( props: ChartLineProps ) => ReactNode;