@web-my-money/blocks 1.0.0

package/dist/app.d.mts

@@ -0,0 +1,454 @@
+import * as React from 'react';
+export { L as LightboxGallery, a as LightboxGalleryProps, b as LightboxImageItem, T as Thumbnail, c as ThumbnailProps } from './index-D5sr_PKq.mjs';
+
+type BannerVariant = "info" | "success" | "warning" | "danger" | "brand";
+interface NotificationBannerProps {
+    variant?: BannerVariant;
+    message: React.ReactNode;
+    /** Link label + href shown after the message */
+    action?: {
+        label: string;
+        href?: string;
+        onClick?: () => void;
+    };
+    /** Allow dismissal — if omitted, banner is permanent */
+    dismissible?: boolean;
+    /** Called when banner is dismissed */
+    onDismiss?: () => void;
+    /** Controlled visibility — manage externally */
+    visible?: boolean;
+    className?: string;
+}
+declare function NotificationBanner({ variant, message, action, dismissible, onDismiss, visible, className, }: NotificationBannerProps): React.JSX.Element;
+
+interface StatCardProps {
+    title: string;
+    value: string | number;
+    /** e.g. "+12.4%" — positive prefixed with + triggers green, negative triggers red */
+    delta?: string;
+    deltaLabel?: string;
+    icon?: React.ReactNode;
+    /** Sparkline or chart slot — render anything here */
+    chart?: React.ReactNode;
+    /** "success" | "warning" | "danger" | "info" — overrides delta-based color */
+    status?: "success" | "warning" | "danger" | "info";
+    className?: string;
+}
+declare function StatCard({ title, value, delta, deltaLabel, icon, chart, status, className, }: StatCardProps): React.JSX.Element;
+
+interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+interface PageHeaderProps {
+    /** Main page title */
+    title: string;
+    /** Short description below the title */
+    description?: string;
+    /** Array of breadcrumb items; last item is the current page (no href needed) */
+    breadcrumb?: BreadcrumbItem[];
+    /** Action buttons / selects rendered right-aligned */
+    actions?: React.ReactNode;
+    /** Extra slot below title row (status badges, tabs, etc.) */
+    below?: React.ReactNode;
+    className?: string;
+}
+declare function PageHeader({ title, description, breadcrumb, actions, below, className, }: PageHeaderProps): React.JSX.Element;
+
+interface EmptyStateProps {
+    icon?: React.ReactNode;
+    title: string;
+    description?: string;
+    /** Primary CTA */
+    action?: React.ReactNode;
+    /** Secondary CTA / link */
+    secondaryAction?: React.ReactNode;
+    /** "page" = full centred section | "card" = compact inline variant */
+    variant?: "page" | "card";
+    className?: string;
+}
+declare function EmptyState({ icon, title, description, action, secondaryAction, variant, className, }: EmptyStateProps): React.JSX.Element;
+
+interface DashboardHeaderProps {
+    pageTitle: string;
+    notificationsCount?: number;
+    actions?: React.ReactNode;
+    className?: string;
+}
+/**
+ * @deprecated Use `AppShell`'s `headerActions` slot (or `PageHeader`/`PageHeaderBanner`
+ * for in-content headers) instead. `DashboardHeader` was the older pairing for
+ * `SidebarNavigation` before `AppShell` unified the chrome. Kept for existing consumers.
+ */
+declare function DashboardHeader({ pageTitle, notificationsCount, actions, className, }: DashboardHeaderProps): React.JSX.Element;
+
+interface MetricCard {
+    title: string;
+    value: string;
+    description?: string;
+    icon?: React.ReactNode;
+}
+interface DataSummaryCardsProps {
+    metrics: MetricCard[];
+    columns?: 2 | 3 | 4;
+    className?: string;
+}
+declare function DataSummaryCards({ metrics, columns, className, }: DataSummaryCardsProps): React.JSX.Element;
+
+interface DataTableRow {
+    id: string;
+    cells: React.ReactNode[];
+    isActive?: boolean;
+}
+interface DataTableProps {
+    title: string;
+    columns: string[];
+    rows: DataTableRow[];
+    activeBadgeLabel?: string;
+    className?: string;
+    /** Rows per page. Omit to render every row with no pager (unchanged default behavior). */
+    pageSize?: number;
+    /** Controlled current page (1-indexed). Uncontrolled (internal state) if omitted. */
+    page?: number;
+    onPageChange?: (page: number) => void;
+}
+declare function DataTable({ title, columns, rows, activeBadgeLabel, className, pageSize, page: controlledPage, onPageChange, }: DataTableProps): React.JSX.Element;
+
+interface SidebarMenuItem {
+    label: string;
+    active?: boolean;
+    href?: string;
+    icon?: React.ReactNode;
+}
+interface SidebarNavigationProps {
+    appName: string;
+    userName?: string;
+    menuItems: SidebarMenuItem[];
+    footer?: React.ReactNode;
+    className?: string;
+}
+/**
+ * @deprecated Use `AppShell` (with `layout="sidebar"`) instead — it is responsive
+ * (mobile drawer + bottom-tabs), supports grouped/collapsible nav via `AppNavGroup`,
+ * and shares the standardized `AppBrand` header. `SidebarNavigation` is desktop-only
+ * with no mobile fallback and a thinner `SidebarMenuItem` model. Kept for existing
+ * consumers; do not use in new code.
+ */
+declare function SidebarNavigation({ appName, userName, menuItems, footer, className, }: SidebarNavigationProps): React.JSX.Element;
+
+interface KPIItem {
+    label: string;
+    value: string | number;
+    delta?: string;
+    deltaLabel?: string;
+    prefix?: string;
+    suffix?: string;
+    status?: "success" | "warning" | "danger" | "neutral";
+}
+interface KPIRowProps {
+    items: KPIItem[];
+    /** Dividers between cells */
+    dividers?: boolean;
+    className?: string;
+}
+declare function KPIRow({ items, dividers, className }: KPIRowProps): React.JSX.Element;
+
+type ActivityType = "task" | "comment" | "alert" | "success" | "info" | "user";
+interface ActivityItem {
+    id: string;
+    type?: ActivityType;
+    title: string;
+    description?: string;
+    timestamp: string;
+    /** Avatar URL or initials */
+    avatar?: string;
+    initials?: string;
+    /** Custom icon slot — overrides type-derived icon */
+    icon?: React.ReactNode;
+    /** Dot color override (Tailwind bg class) */
+    dotColor?: string;
+    meta?: string;
+}
+interface ActivityFeedProps {
+    items: ActivityItem[];
+    /** Show timeline connector line */
+    timeline?: boolean;
+    /** Compact row layout instead of card */
+    compact?: boolean;
+    className?: string;
+    emptyMessage?: string;
+}
+declare function ActivityFeed({ items, timeline, compact, className, emptyMessage, }: ActivityFeedProps): React.JSX.Element;
+
+interface AppNavItem {
+    label: string;
+    href?: string;
+    icon?: React.ReactNode;
+    active?: boolean;
+    /** count badge (e.g. overdue) */
+    badge?: number | string;
+    onClick?: () => void;
+    /** Children — a dropdown (top layout) or an indented sub-list (sidebar). */
+    items?: AppNavItem[];
+    /** Shorter label for the mobile bottom tab bar (defaults to `label`). */
+    shortLabel?: string;
+    /** Opens in a new tab (target="_blank" rel="noopener noreferrer"), bypassing `renderLink`. */
+    external?: boolean;
+}
+interface AppNavGroup {
+    /** Uppercase section header. Omit for an ungrouped run of items. */
+    label?: string;
+    items: AppNavItem[];
+    /** Sidebar: render the section as a collapsible disclosure. */
+    collapsible?: boolean;
+    /** Initial open state when `collapsible`. Default true. */
+    defaultOpen?: boolean;
+}
+/** Flat items OR grouped sections — flat stays valid (no breaking change). */
+type AppNav = AppNavItem[] | AppNavGroup[];
+type AppLayout = "sidebar" | "top";
+interface AppShellProps {
+    /** App name shown by the brand lockup */
+    appName: string;
+    /** Muted prefix before the name (default "WMM"; "" hides it). */
+    brandPrefix?: string;
+    /** Logo/mark node (defaults to a mini-logo placeholder chip). */
+    logo?: React.ReactNode;
+    /** Small line under the app name (e.g. "Internal admin"). */
+    brandSubtitle?: string;
+    /** Trailing brand badge after a divider (e.g. "OS"). */
+    brandBadge?: React.ReactNode;
+    nav: AppNav;
+    /** Bottom-tab subset for mobile (defaults to the first 5 leaf items). */
+    mobileTabs?: AppNavItem[];
+    /** Footer user block (avatar + name); rendered at sidebar bottom / brand menu. */
+    user?: React.ReactNode;
+    /** Header actions (theme toggle, notifications, search, LayoutToggle…). */
+    headerActions?: React.ReactNode;
+    /** Extra sidebar footer content above the user block. */
+    sidebarFooter?: React.ReactNode;
+    /** "sidebar" (default) or "top". Uncontrolled unless `onLayoutChange` given. */
+    layout?: AppLayout;
+    /** Uncontrolled initial layout (persisted to localStorage). Default "sidebar". */
+    defaultLayout?: AppLayout;
+    /** Controlled layout change handler. */
+    onLayoutChange?: (layout: AppLayout) => void;
+    /** Current route — auto-derives `active` for items whose `active` is unset. */
+    pathname?: string;
+    /** Center content in a max-w-7xl container. */
+    contained?: boolean;
+    defaultCollapsed?: boolean;
+    /** Render function for links — pass next/link's Link to get client nav. */
+    renderLink?: (props: {
+        href: string;
+        className?: string;
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+}
+/** Standalone persisted layout preference — for apps driving AppShell in controlled mode. */
+declare function useLayoutPreference(defaultLayout?: AppLayout): [AppLayout, (l: AppLayout) => void];
+/** Button that flips the enclosing AppShell between sidebar and top layouts. */
+declare function LayoutToggle({ className }: {
+    className?: string;
+}): React.JSX.Element | null;
+/**
+ * WMM app shell — the internal-app chrome used across the OS. One component, two
+ * layouts (`sidebar` default, or `top`) sharing one nav model + brand lockup, so a
+ * runtime toggle needs no data changes. Sidebar: collapsible rail + mobile drawer +
+ * bottom tabs. Top: slim sticky bar with a11y dropdowns + mobile sheet. Brand-agnostic.
+ */
+declare function AppShell({ appName, brandPrefix, logo, brandSubtitle, brandBadge, nav, mobileTabs, user, headerActions, sidebarFooter, layout: layoutProp, defaultLayout, onLayoutChange, pathname, contained, defaultCollapsed, renderLink, children, className, }: AppShellProps): React.JSX.Element;
+
+interface AppBrandProps {
+    /** App name — e.g. "Tasks". Rendered accented after `prefix` ("WMM Tasks"). */
+    appName: string;
+    /** Muted text before the name. Default "WMM"; pass "" to show `appName` alone. */
+    prefix?: string;
+    /** Real logo mark (e.g. <WmmLogo variant="mark" />). Omit → mini-logo placeholder. */
+    logo?: React.ReactNode;
+    /** Small second line under the title (e.g. "Internal admin"). */
+    subtitle?: string;
+    /** Trailing badge shown after a divider (e.g. "OS"). */
+    badge?: React.ReactNode;
+    /** Wrap the whole lockup in a link. */
+    href?: string;
+    /** Icon-only (sidebar rail / collapsed). Hides text + badge + subtitle. */
+    collapsed?: boolean;
+    /** Visual scale. Default "md". */
+    size?: "sm" | "md";
+    /** Pass a framework link (e.g. next/link) for client-side nav. */
+    renderLink?: (props: {
+        href: string;
+        className?: string;
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    className?: string;
+}
+/**
+ * Standardized WMM app identity lockup — the top-left brand used by BOTH the
+ * sidebar and top-nav shells, on web and mobile, so every app reads as one family.
+ *
+ * Renders `logo` + a two-tone title (muted `prefix` + accented `appName`), with an
+ * optional `subtitle` line and trailing `badge`. When no `logo` is supplied it falls
+ * back to a mini-logo placeholder: a primary chip with the app's first letter.
+ * Brand-agnostic — colors come from token CSS vars, so any brand reskins it.
+ */
+declare function AppBrand({ appName, prefix, logo, subtitle, badge, href, collapsed, size, renderLink, className, }: AppBrandProps): React.JSX.Element;
+
+interface SubTabItem<T extends string> {
+    id: T;
+    label: string;
+    icon?: React.ReactNode;
+}
+interface SubTabsProps<T extends string> {
+    items: SubTabItem<T>[];
+    value: T;
+    onChange: (id: T) => void;
+    className?: string;
+    /** Accessible label for the tablist. */
+    "aria-label"?: string;
+}
+/**
+ * In-page secondary navigation — a segmented pill switcher for splitting one page
+ * into sub-views (e.g. Pay People ⊃ {Pay run, Wise}). Pairs with either app shell.
+ * Brand-agnostic (token CSS vars). Lifted from wmm-finance-hr's proven pattern.
+ */
+declare function SubTabs<T extends string>({ items, value, onChange, className, "aria-label": ariaLabel, }: SubTabsProps<T>): React.JSX.Element;
+
+interface PageHeaderBannerProps {
+    title: string;
+    subtitle?: string;
+    /** right-aligned actions (buttons) */
+    actions?: React.ReactNode;
+    /** gradient wash behind the banner (defaults to the brand primary tint) */
+    gradient?: boolean;
+    icon?: React.ReactNode;
+    className?: string;
+}
+/** OS-style page header — gradient-tinted banner with title, subtitle, actions. */
+declare function PageHeaderBanner({ title, subtitle, actions, gradient, icon, className, }: PageHeaderBannerProps): React.JSX.Element;
+
+interface GlassPanelProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** stronger frosted fill */
+    strong?: boolean;
+    /** add the brand glow shadow (dark themes) */
+    glow?: boolean;
+}
+/** Glassmorphism panel — frosted blur + hairline border. Reads token glass vars
+ * (falls back gracefully on themes that don't define them). */
+declare function GlassPanel({ strong, glow, className, style, ...props }: GlassPanelProps): React.JSX.Element;
+
+interface BrandFrameProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Brand mark rendered as a faint watermark inside the frame (pass <WmmLogo …/>). */
+    watermark?: React.ReactNode;
+    watermarkPosition?: "top-right" | "bottom-right" | "center";
+    /** Watermark opacity 0–1 (default 0.06). */
+    watermarkOpacity?: number;
+    /** Soft brand glow shadow (reads --shadow-glow / --primary). */
+    glow?: boolean;
+    /** Frosted glass fill instead of solid card. */
+    glass?: boolean;
+    /** Animated shine sweep across the top edge (brand gradient). */
+    animated?: boolean;
+    /** Header row (title / actions) above the content. */
+    header?: React.ReactNode;
+    /** Slot rendered absolutely behind the content (e.g. an AuroraBackground or 3D render). */
+    backdrop?: React.ReactNode;
+}
+/**
+ * A branded container — rounded token surface with an optional glow, glass fill, a faint
+ * logo watermark, an animated brand shine, and a backdrop slot for effects/renders.
+ * Brand-agnostic: the watermark is a passed node and all colour comes from token vars, so
+ * WMM (pass <WmmLogo/>) or any client brand reuses it. This is the "nice container that
+ * accepts animations" — drop content in as children.
+ */
+declare function BrandFrame({ watermark, watermarkPosition, watermarkOpacity, glow, glass, animated, header, backdrop, className, children, style, ...props }: BrandFrameProps): React.JSX.Element;
+
+/**
+ * The shared shape for a Next.js Server Action's return value — pairs with
+ * `useActionRunner`/`useOptimisticAction`. Keep every server action returning
+ * this instead of throwing, so the client can branch on `.ok` without a
+ * try/catch around every call site.
+ *
+ *   "use server";
+ *   export async function setStatus(id: string, status: string): Promise<ActionResult> {
+ *     const { error } = await supabase.from("tasks").update({ status }).eq("id", id);
+ *     return error ? { ok: false, error: error.message } : { ok: true, data: undefined };
+ *   }
+ */
+type ActionResult<T = void> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+
+interface RunOptions<T> {
+    /** Toast title on success. Function form receives the action's `data`. */
+    successMessage?: string | ((data: T) => string);
+    /** Toast title on failure. Defaults to the ActionResult's own `error` string. */
+    errorMessage?: string | ((error: string) => string);
+    /** Adds an inline "Undo" (or custom label) button to the success toast. */
+    undo?: {
+        label?: string;
+        action: () => Promise<ActionResult<unknown>>;
+    };
+    onSuccess?: (data: T) => void;
+    onError?: (error: string) => void;
+    /** Runs after either branch, success or failure — for busy-flag cleanup, refetch, etc. */
+    onSettled?: () => void;
+}
+/**
+ * The "run a server action from a click handler" wrapper used throughout
+ * wmm-tasks' slide-over — generalized: busy flag, toast on success/failure,
+ * optional inline Undo action. Requires `<ToastProvider>` mounted once near
+ * the app root (see `@web-my-money/primitives/toast`).
+ *
+ *   const { run, pending } = useActionRunner();
+ *   <Button disabled={pending} onClick={() => run(
+ *     () => archiveContractor(id),
+ *     { successMessage: "Archived", undo: { action: () => restoreContractor(id) } },
+ *   )} />
+ */
+declare function useActionRunner(): {
+    run: <T>(action: () => Promise<ActionResult<T>>, options?: RunOptions<T>) => Promise<ActionResult<T>>;
+    pending: boolean;
+};
+
+/**
+ * Server Actions + optimistic UI, the React 19 way: wraps `useOptimistic` +
+ * `useTransition` so the optimistic value is set correctly *inside* a
+ * transition (required — React discards/warns on optimistic updates set
+ * outside one) and the real mutation runs alongside it. On success the real
+ * data eventually replaces the optimistic value on next render; on failure,
+ * `useOptimistic` automatically reverts once the transition settles — pair
+ * with `onResult` to also toast the error.
+ *
+ *   const [optimisticStatus, applyStatus, pending] = useOptimisticAction(
+ *     task.status,
+ *     (_prev, next: Status) => next,
+ *   );
+ *   <StatusSelect
+ *     value={optimisticStatus}
+ *     disabled={pending}
+ *     onChange={(next) => applyStatus(next, () => setStatus(task.id, next))}
+ *   />
+ */
+declare function useOptimisticAction<State, Optimistic>(state: State, reducer: (state: State, optimisticValue: Optimistic) => State): readonly [State, <T>(optimisticValue: Optimistic, action: () => Promise<ActionResult<T>>, onResult?: (result: ActionResult<T>) => void) => void, boolean];
+
+interface AppearanceSettingsProps {
+    className?: string;
+}
+/**
+ * Settings → Appearance section — pairs the DS's `ThemeToggle` (light/dark/wmm)
+ * with `FontSizeToggle` (md/lg/xl text scale), both from
+ * `@web-my-money/tokens/react`. Meant to drop straight into any app's
+ * Settings → Appearance page (wmm-os's `/settings` page is the intended first
+ * consumer — not wired in from here). Brand-agnostic (token CSS vars only).
+ */
+declare function AppearanceSettings({ className }: AppearanceSettingsProps): React.JSX.Element;
+
+export { type ActionResult, ActivityFeed, type ActivityFeedProps, type ActivityItem, type ActivityType, AppBrand, type AppBrandProps, type AppLayout, type AppNav, type AppNavGroup, type AppNavItem, AppShell, type AppShellProps, AppearanceSettings, type AppearanceSettingsProps, type BannerVariant, BrandFrame, type BrandFrameProps, type BreadcrumbItem, DashboardHeader, type DashboardHeaderProps, DataSummaryCards, type DataSummaryCardsProps, DataTable, type DataTableProps, type DataTableRow, EmptyState, type EmptyStateProps, GlassPanel, type GlassPanelProps, type KPIItem, KPIRow, type KPIRowProps, LayoutToggle, type MetricCard, NotificationBanner, type NotificationBannerProps, PageHeader, PageHeaderBanner, type PageHeaderBannerProps, type PageHeaderProps, type RunOptions, type SidebarMenuItem, SidebarNavigation, type SidebarNavigationProps, StatCard, type StatCardProps, type SubTabItem, SubTabs, type SubTabsProps, useActionRunner, useLayoutPreference, useOptimisticAction };