@leandrosk/dashboard 3.5.5

package/src/lib/framework/history-entry/history-entry.tsx

@@ -0,0 +1,129 @@
+import { HistoryEntryItem } from '@/vdb/framework/extension-api/types/index.js';
+import { cn } from '@/vdb/lib/utils.js';
+import React from 'react';
+import { HistoryEntryDate } from '../../components/shared/history-timeline/history-entry-date.js';
+
+/**
+ * @description
+ * The props for the {@link HistoryEntry} component.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export interface HistoryEntryProps {
+    /**
+     * @description
+     * The entry itself, which will get passed down to your custom component
+     */
+    entry: HistoryEntryItem;
+    /**
+     * @description
+     * The title of the entry
+     */
+    title: string | React.ReactNode;
+    /**
+     * @description
+     * An icon which is used to represent the entry. Note that this will only
+     * display if `isPrimary` is `true`.
+     */
+    timelineIcon?: React.ReactNode;
+    /**
+     * @description
+     * Optional tailwind classes to apply to the icon. For instance
+     *
+     * ```ts
+     * const success = 'bg-success text-success-foreground';
+     * const destructive = 'bg-destructive text-destructive-foreground';
+     * ```
+     */
+    timelineIconClassName?: string;
+    /**
+     * @description
+     * The name to display of "who did the action". For instance:
+     *
+     * ```ts
+     * const getActorName = (entry: HistoryEntryItem) => {
+     *     if (entry.administrator) {
+     *         return `${entry.administrator.firstName} ${entry.administrator.lastName}`;
+     *     } else if (entity?.customer) {
+     *         return `${entity.customer.firstName} ${entity.customer.lastName}`;
+     *     }
+     *     return '';
+     * };
+     * ```
+     */
+    actorName?: string;
+    children: React.ReactNode;
+    /**
+     * @description
+     * When set to `true`, the timeline entry will feature the specified icon and will not
+     * be collapsible.
+     */
+    isPrimary?: boolean;
+}
+
+/**
+ * @description
+ * A component which is used to display a history entry in the order/customer history timeline.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export function HistoryEntry({
+    entry,
+    timelineIcon,
+    timelineIconClassName,
+    actorName,
+    title,
+    children,
+    isPrimary = true,
+}: Readonly<HistoryEntryProps>) {
+    return (
+        <div key={entry.id} className="relative group">
+            <div
+                className={`flex gap-3 p-3 rounded-lg hover:bg-muted/30 transition-colors ${!isPrimary ? 'opacity-90' : ''}`}
+            >
+                <div className={cn(`relative z-10 flex-shrink-0`, isPrimary ? 'ml-0' : 'ml-2 mt-1')}>
+                    <div
+                        className={`rounded-full flex items-center justify-center ${isPrimary ? 'h-6 w-6' : 'h-2 w-2 border'} ${timelineIconClassName ?? ''}  ${isPrimary ? 'shadow-sm' : 'shadow-none'}`}
+                    >
+                        <div className={isPrimary ? 'text-current scale-80' : 'text-current scale-0'}>
+                            {timelineIcon ?? ''}
+                        </div>
+                    </div>
+                </div>
+
+                <div className="flex-1 min-w-0">
+                    <div className="flex items-start justify-between">
+                        <div className="flex-1 min-w-0">
+                            <h4
+                                className={`text-sm ${isPrimary ? 'font-medium text-foreground' : 'font-normal text-muted-foreground'}`}
+                            >
+                                {title}
+                            </h4>
+                            <div className="mt-1">{children}</div>
+                        </div>
+
+                        <div className="flex items-center gap-2 ml-4 flex-shrink-0">
+                            <div className="text-right">
+                                <HistoryEntryDate
+                                    date={entry.createdAt}
+                                    className={`text-xs cursor-help ${isPrimary ? 'text-muted-foreground' : 'text-muted-foreground/70'}`}
+                                />
+                                {actorName && (
+                                    <div
+                                        className={`text-xs ${isPrimary ? 'text-muted-foreground' : 'text-muted-foreground/70'}`}
+                                    >
+                                        {actorName}
+                                    </div>
+                                )}
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}

package/src/lib/framework/layout-engine/custom-form-page.stories.tsx

@@ -0,0 +1,344 @@
+import { FormFieldWrapper } from '@/vdb/components/shared/form-field-wrapper.js';
+import { Button } from '@/vdb/components/ui/button.js';
+import { Input } from '@/vdb/components/ui/input.js';
+import { Textarea } from '@/vdb/components/ui/textarea.js';
+import { graphql } from '@/vdb/graphql/graphql.js';
+import { Trans } from '@lingui/react/macro';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { RouterContextProvider } from '@tanstack/react-router';
+import { useForm } from 'react-hook-form';
+import { createDemoRoute } from '../../../../.storybook/providers.js';
+import {
+    DetailFormGrid,
+    Page,
+    PageActionBar,
+    PageActionBarRight,
+    PageBlock,
+    PageLayout,
+    PageTitle,
+} from './page-layout.js';
+
+// Sample GraphQL query for a product detail
+const productFragment = graphql(`
+    fragment ProductDetailForForm on Product {
+        id
+        createdAt
+        updatedAt
+        name
+        slug
+        description
+        enabled
+    }
+`);
+
+const productQuery = graphql(
+    `
+        query ProductForCustomForm($id: ID!) {
+            product(id: $id) {
+                ...ProductDetailForForm
+            }
+        }
+    `,
+    [productFragment],
+);
+
+interface ProductFormData {
+    name: string;
+    slug: string;
+    description: string;
+    enabled: boolean;
+}
+
+const meta = {
+    title: 'Layout/Custom Form Page',
+    parameters: {
+        layout: 'fullscreen',
+    },
+    tags: ['autodocs'],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * This example shows how to create a custom form page using FormFieldWrapper
+ * with a product entity. This pattern is useful when you want full control over
+ * the form layout instead of using the automated DetailPage component.
+ */
+export const ProductCustomForm: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        const form = useForm<ProductFormData>({
+            defaultValues: {
+                name: 'Wireless Headphones',
+                slug: 'wireless-headphones',
+                description: 'High-quality wireless headphones with active noise cancellation.',
+                enabled: true,
+            },
+        });
+
+        const onSubmit = (data: ProductFormData) => {
+            console.log('Form submitted:', data);
+            // In a real app, you would call your update mutation here
+        };
+
+        return (
+            <RouterContextProvider router={router}>
+                <Page
+                    pageId="product-custom-detail"
+                    form={form}
+                    submitHandler={form.handleSubmit(onSubmit)}
+                    entity={{
+                        id: '1',
+                        createdAt: '2024-01-01T00:00:00.000Z',
+                        updatedAt: '2024-01-15T00:00:00.000Z',
+                    }}
+                >
+                    <PageTitle>
+                        <Trans>Product: Wireless Headphones</Trans>
+                    </PageTitle>
+                    <PageActionBar>
+                        <PageActionBarRight>
+                            <Button type="submit" disabled={!form.formState.isDirty}>
+                                <Trans>Save Changes</Trans>
+                            </Button>
+                        </PageActionBarRight>
+                    </PageActionBar>
+                    <PageLayout>
+                        <PageBlock
+                            column="main"
+                            blockId="product-details"
+                            title={<Trans>Product Details</Trans>}
+                            description={<Trans>Basic information about the product</Trans>}
+                        >
+                            <DetailFormGrid>
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="name"
+                                    label={<Trans>Product Name</Trans>}
+                                    description={<Trans>The display name of the product</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="slug"
+                                    label={<Trans>Slug</Trans>}
+                                    description={<Trans>URL-friendly identifier</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                            </DetailFormGrid>
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="description"
+                                label={<Trans>Description</Trans>}
+                                render={({ field }) => <Textarea {...field} rows={4} />}
+                            />
+                        </PageBlock>
+                        <PageBlock column="side" blockId="product-status" title={<Trans>Status</Trans>}>
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="enabled"
+                                label={<Trans>Enabled</Trans>}
+                                description={<Trans>Whether this product is active</Trans>}
+                                render={({ field }) => (
+                                    <div className="flex items-center">
+                                        <input
+                                            type="checkbox"
+                                            checked={field.value}
+                                            onChange={field.onChange}
+                                            className="mr-2"
+                                        />
+                                        <span className="text-sm">
+                                            {field.value ? (
+                                                <Trans>Product is enabled</Trans>
+                                            ) : (
+                                                <Trans>Product is disabled</Trans>
+                                            )}
+                                        </span>
+                                    </div>
+                                )}
+                            />
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+/**
+ * This example shows a more complex form with multiple blocks and varied form fields.
+ */
+export const ComplexCustomForm: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        const form = useForm({
+            defaultValues: {
+                // Basic Info
+                name: 'Premium Laptop',
+                slug: 'premium-laptop',
+                sku: 'LAPTOP-001',
+                // Pricing
+                price: 1299.99,
+                salePrice: null,
+                costPrice: 899.0,
+                // Inventory
+                stockOnHand: 50,
+                trackInventory: true,
+                // Details
+                description: 'High-performance laptop for professionals',
+                shortDescription: 'Professional laptop',
+                // SEO
+                metaTitle: '',
+                metaDescription: '',
+            },
+        });
+
+        const onSubmit = (data: any) => {
+            console.log('Form submitted:', data);
+        };
+
+        return (
+            <RouterContextProvider router={router}>
+                <Page
+                    pageId="product-complex-detail"
+                    form={form}
+                    submitHandler={form.handleSubmit(onSubmit)}
+                    entity={{ id: '2', createdAt: '2024-01-01', updatedAt: '2024-01-15' }}
+                >
+                    <PageTitle>
+                        <Trans>Product: Premium Laptop</Trans>
+                    </PageTitle>
+                    <PageActionBar>
+                        <PageActionBarRight>
+                            <Button variant="outline" type="button">
+                                <Trans>Cancel</Trans>
+                            </Button>
+                            <Button type="submit" disabled={!form.formState.isDirty}>
+                                <Trans>Save Changes</Trans>
+                            </Button>
+                        </PageActionBarRight>
+                    </PageActionBar>
+                    <PageLayout>
+                        <PageBlock
+                            column="main"
+                            blockId="basic-info"
+                            title={<Trans>Basic Information</Trans>}
+                        >
+                            <DetailFormGrid>
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="name"
+                                    label={<Trans>Product Name</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="sku"
+                                    label={<Trans>SKU</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="slug"
+                                    label={<Trans>Slug</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                            </DetailFormGrid>
+                        </PageBlock>
+
+                        <PageBlock column="main" blockId="description" title={<Trans>Description</Trans>}>
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="shortDescription"
+                                label={<Trans>Short Description</Trans>}
+                                render={({ field }) => <Input {...field} />}
+                            />
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="description"
+                                label={<Trans>Full Description</Trans>}
+                                render={({ field }) => <Textarea {...field} rows={6} />}
+                            />
+                        </PageBlock>
+
+                        <PageBlock column="main" blockId="pricing" title={<Trans>Pricing</Trans>}>
+                            <DetailFormGrid>
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="price"
+                                    label={<Trans>Price</Trans>}
+                                    render={({ field }) => <Input {...field} type="number" step="0.01" />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="salePrice"
+                                    label={<Trans>Sale Price</Trans>}
+                                    description={<Trans>Optional discounted price</Trans>}
+                                    render={({ field }) => (
+                                        <Input
+                                            {...field}
+                                            type="number"
+                                            step="0.01"
+                                            value={field.value ?? ''}
+                                        />
+                                    )}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="costPrice"
+                                    label={<Trans>Cost Price</Trans>}
+                                    description={<Trans>Your cost for this product</Trans>}
+                                    render={({ field }) => <Input {...field} type="number" step="0.01" />}
+                                />
+                            </DetailFormGrid>
+                        </PageBlock>
+
+                        <PageBlock column="side" blockId="inventory" title={<Trans>Inventory</Trans>}>
+                            <div className="space-y-4">
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="trackInventory"
+                                    label={<Trans>Track Inventory</Trans>}
+                                    render={({ field }) => (
+                                        <div className="flex items-center">
+                                            <input
+                                                type="checkbox"
+                                                checked={field.value}
+                                                onChange={field.onChange}
+                                                className="mr-2"
+                                            />
+                                        </div>
+                                    )}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="stockOnHand"
+                                    label={<Trans>Stock on Hand</Trans>}
+                                    render={({ field }) => <Input {...field} type="number" />}
+                                />
+                            </div>
+                        </PageBlock>
+
+                        <PageBlock column="side" blockId="seo" title={<Trans>SEO</Trans>}>
+                            <div className="space-y-4">
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="metaTitle"
+                                    label={<Trans>Meta Title</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="metaDescription"
+                                    label={<Trans>Meta Description</Trans>}
+                                    render={({ field }) => <Textarea {...field} rows={3} />}
+                                />
+                            </div>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};

package/src/lib/framework/layout-engine/dev-mode-button.tsx

@@ -0,0 +1,24 @@
+import { Button } from '@/vdb/components/ui/button.js';
+import { cn } from '@/vdb/lib/utils.js';
+import { CodeXmlIcon } from 'lucide-react';
+import { forwardRef } from 'react';
+
+export const DevModeButton = forwardRef<HTMLButtonElement, React.ComponentProps<typeof Button>>(
+    (props, ref) => {
+        const { className, ...rest } = props;
+        return (
+            <Button
+                ref={ref}
+                variant="secondary"
+                size="icon"
+                className={cn(
+                    'h-8 w-8 rounded-full bg-dev-mode/20 hover:bg-dev-mode/30 border border-dev-mode/20 shadow-sm',
+                    className,
+                )}
+                {...rest}
+            >
+                <CodeXmlIcon className="text-dev-mode w-4 h-4" />
+            </Button>
+        );
+    },
+);

package/src/lib/framework/layout-engine/layout-extensions.ts

@@ -0,0 +1,27 @@
+import { DashboardActionBarItem, DashboardPageBlockDefinition } from '../extension-api/types/layout.js';
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('dashboardActionBarItemRegistry', new Map<string, DashboardActionBarItem[]>());
+globalRegistry.register('dashboardPageBlockRegistry', new Map<string, DashboardPageBlockDefinition[]>());
+
+export function registerDashboardActionBarItem(item: DashboardActionBarItem) {
+    globalRegistry.set('dashboardActionBarItemRegistry', map => {
+        map.set(item.pageId, [...(map.get(item.pageId) ?? []), item]);
+        return map;
+    });
+}
+
+export function getDashboardActionBarItems(pageId: string) {
+    return globalRegistry.get('dashboardActionBarItemRegistry').get(pageId) ?? [];
+}
+
+export function registerDashboardPageBlock(block: DashboardPageBlockDefinition) {
+    globalRegistry.set('dashboardPageBlockRegistry', map => {
+        map.set(block.location.pageId, [...(map.get(block.location.pageId) ?? []), block]);
+        return map;
+    });
+}
+
+export function getDashboardPageBlocks(pageId: string) {
+    return globalRegistry.get('dashboardPageBlockRegistry').get(pageId) ?? [];
+}

package/src/lib/framework/layout-engine/location-wrapper.tsx

@@ -0,0 +1,122 @@
+import { CopyableText } from '@/vdb/components/shared/copyable-text.js';
+import { Popover, PopoverContent, PopoverTrigger } from '@/vdb/components/ui/popover.js';
+import { usePageBlock } from '@/vdb/hooks/use-page-block.js';
+import { usePage } from '@/vdb/hooks/use-page.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
+import { cn } from '@/vdb/lib/utils.js';
+import React, { useEffect, useState } from 'react';
+import { DevModeButton } from './dev-mode-button.js';
+
+// Singleton state for hover tracking
+let globalHoveredId: string | null = null;
+const hoverListeners: Set<(id: string | null) => void> = new Set();
+
+const setGlobalHoveredId = (id: string | null) => {
+    globalHoveredId = id;
+    hoverListeners.forEach(listener => listener(id));
+};
+
+export interface LocationWrapperProps {
+    children: React.ReactNode;
+    identifier?: string;
+}
+
+export function LocationWrapper({ children, identifier }: Readonly<LocationWrapperProps>) {
+    const page = usePage();
+    const pageBlock = usePageBlock({ optional: true });
+    const { settings } = useUserSettings();
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+    const blockId = pageBlock?.blockId ?? null;
+    const isPageWrapper = !blockId;
+
+    const [hoveredId, setHoveredId] = useState<string | null>(globalHoveredId);
+    const id = `${page.pageId}-${blockId ?? 'page'}-${identifier ?? ''}`;
+    const isHovered = hoveredId === id;
+
+    // Subscribe to global hover changes
+    useEffect(() => {
+        const listener = (newHoveredId: string | null) => {
+            setHoveredId(newHoveredId);
+        };
+        hoverListeners.add(listener);
+        return () => {
+            hoverListeners.delete(listener);
+        };
+    }, []);
+
+    const setHoverId = (id: string | null) => {
+        setGlobalHoveredId(id);
+    };
+
+    const handleMouseEnter = () => {
+        // Set this element as hovered
+        setHoverId(id);
+    };
+
+    const handleMouseLeave = () => {
+        // If we're at the top level (page wrapper), go to null
+        // If we're at block level, go to page level
+        // If we're at identifier level, go to block level
+        if (isPageWrapper) {
+            setHoverId(null);
+        } else if (blockId && !identifier) {
+            // Block level - go to page level
+            setHoverId(`${page.pageId}-page-`);
+        } else if (identifier) {
+            // Identifier level - go to block level
+            setHoverId(`${page.pageId}-${blockId}-`);
+        }
+    };
+
+    if (settings.devMode) {
+        const pageId = page.pageId;
+        return (
+            <div
+                className={cn(
+                    `ring-2 transition-all ring-offset-4 ring-offset-background delay-50 relative`,
+                    isHovered || isPopoverOpen ? 'ring-dev-mode' : 'ring-transparent',
+                    isPageWrapper ? 'ring-offset-8' : '',
+                    identifier ? 'rounded-md' : 'rounded',
+                )}
+                onMouseEnter={handleMouseEnter}
+                onMouseLeave={handleMouseLeave}
+            >
+                <div
+                    className={`absolute top-1 right-1 transition-all delay-50 z-10 ${isHovered || isPopoverOpen ? 'visible' : 'invisible'}`}
+                >
+                    <Popover open={isPopoverOpen} onOpenChange={setIsPopoverOpen}>
+                        <PopoverTrigger asChild>
+                            <DevModeButton />
+                        </PopoverTrigger>
+                        <PopoverContent className="w-48 p-3">
+                            <div className="space-y-2">
+                                <div className="space-y-1">
+                                    {pageId && (
+                                        <div className="text-xs">
+                                            <div className="text-muted-foreground mb-0.5">pageId</div>
+                                            <CopyableText text={pageId} />
+                                        </div>
+                                    )}
+                                    {blockId && (
+                                        <div className="text-xs">
+                                            <div className="text-muted-foreground mb-0.5">blockId</div>
+                                            <CopyableText text={blockId} />
+                                        </div>
+                                    )}
+                                    {identifier && (
+                                        <div className="text-xs">
+                                            <div className="text-muted-foreground mb-0.5">identifier</div>
+                                            <CopyableText text={identifier} />
+                                        </div>
+                                    )}
+                                </div>
+                            </div>
+                        </PopoverContent>
+                    </Popover>
+                </div>
+                {children}
+            </div>
+        );
+    }
+    return children;
+}

package/src/lib/framework/layout-engine/page-block-provider.tsx

@@ -0,0 +1,6 @@
+import { PageBlockProps } from '@/vdb/framework/layout-engine/page-layout.js';
+import { createContext } from 'react';
+
+export type PageBlockContextValue = Pick<PageBlockProps, 'blockId' | 'column' | 'title' | 'description'>;
+
+export const PageBlockContext = createContext<PageBlockContextValue | undefined>(undefined);