@vertesia/ui 0.24.0-dev.202601221707

package/src/features/store/objects/layout/knowledge.md

@@ -0,0 +1,239 @@
+# Layout System Knowledge
+
+## Overview
+The layout system provides a flexible way to define table and grid layouts for content objects and documents.
+
+## Column Layout System
+
+### Column Layout Definition
+```typescript
+interface ColumnLayout {
+    name: string;       // Display name of the column
+    field: string;      // Dot notation path to the data field
+    fallback?: string;  // Fallback field if primary is empty
+    type?: string;      // Data type for the column
+    default?: any;      // Default value if field is undefined
+}
+```
+
+### Field Path Notation
+- Uses dot notation to access nested properties
+- Example: `properties.title` accesses title in properties object
+- Special path "." returns the entire object
+- Supports fallback fields with the `fallback` property
+- Nested paths: `user.profile.name`
+- Array access: `items.0.name`
+
+### Available Column Types
+Complete list of supported types:
+
+1. **string** - Text display
+2. **number** - Numeric display
+3. **date** - Date/time display
+4. **objectId** - object id with preview button
+5. **objectName** - object name display
+6. **objectLink** - *(deprecated)* alias for objectId, kept for backward compatibility
+
+### Column Types and Renderers
+Built-in renderers with parameters:
+
+1. **string**
+   - `slice`: Take substring from index
+   - `max_length`: Maximum string length
+   - `upper`: Convert to uppercase
+   - `lower`: Convert to lowercase
+   - `capitalize`: Capitalize first letter
+   - `ellipsis`: Add ... at end
+
+2. **number**
+   - `currency`: Format as currency (e.g., USD)
+   - `decimals`: Number of decimal places (default: 2)
+
+3. **date**
+   - `localized`: Use localized format (e.g., "LLL")
+   - `relative`: Use relative time ("fromNow"/"toNow")
+
+4. **objectId**
+   - `slice`: Take substring from index
+
+
+### Parameter Syntax
+Parameters are added using URL query string syntax:
+```typescript
+"type": "string?max_length=50&ellipsis"
+"type": "number?currency=USD&decimals=2"
+"type": "date?relative=fromNow"
+```
+
+## Layout Configuration Examples
+
+### Basic Table Layout
+```json
+{
+  "layout": [
+    {
+      "name": "Title",
+      "field": "properties.title",
+      "fallback": "name",
+      "type": "string"
+    },
+    {
+      "name": "Created",
+      "field": "created_at",
+      "type": "date?relative=fromNow"
+    }
+  ]
+}
+```
+
+### Complex Table Layout
+```json
+{
+  "layout": [
+    {
+      "name": "ID",
+      "field": "id",
+      "type": "objectId?slice=-7"
+    },
+    {
+      "name": "Name",
+      "field": ".",
+      "type": "objectName"
+    },
+    {
+      "name": "Price",
+      "field": "price",
+      "type": "number?currency=USD&decimals=2",
+      "default": 0
+    },
+    {
+      "name": "Status",
+      "field": "status",
+      "type": "string?upper=true"
+    },
+    {
+      "name": "Last Update",
+      "field": "updated_at",
+      "type": "date?localized=LLL"
+    }
+  ]
+}
+```
+
+### Search Results Layout
+```json
+{
+  "layout": [
+    {
+      "name": "Document",
+      "field": ".",
+      "type": "objectName"
+    },
+    {
+      "name": "Score",
+      "field": "score",
+      "type": "number?decimals=3"
+    },
+    {
+      "name": "Type",
+      "field": "type",
+      "type": "typeLink"
+    }
+  ]
+}
+```
+
+## Common Error Cases
+
+### Field Path Errors
+- Invalid path: Using undefined nested properties
+- Wrong case: Property names are case-sensitive
+- Missing fallback: No fallback for potentially undefined fields
+
+### Type Parameter Errors
+- Invalid parameter names: Using undefined parameters
+- Wrong parameter values: Using incorrect value types
+- Missing required parameters: Not providing required parameters
+
+### Best Practices to Avoid Errors
+- Always validate field paths exist in your data
+- Provide fallbacks for optional fields
+- Use type parameters appropriately
+- Test layouts with empty/null data
+- Verify parameter values are correct
+
+## Grid Layout System
+
+### Document Grid Layout
+- Supports responsive grid layouts
+- Default configuration: `lg:grid-cols-6`
+- Handles document icons and empty states
+- Supports drag and drop functionality
+
+### Grid Layout Features
+- Responsive column sizing
+- Empty state handling
+- Loading states
+- Drag and drop file upload
+- Type selection modal integration
+
+## Best Practices
+
+### Column Definition
+- Always provide a name for clarity
+- Use fallbacks for critical fields
+- Specify type when needed for formatting
+- Keep field paths simple and clear
+- Use type parameters for fine-grained control
+
+### Layout Implementation
+- Use consistent naming conventions
+- Implement proper loading states
+- Handle empty states gracefully
+- Support responsive layouts
+- Consider selection requirements
+
+### Data Access
+- Use dot notation for nested data
+- Provide fallback values
+- Handle missing data gracefully
+- Support type-safe access
+- Use default values where appropriate
+
+## Validation Rules
+
+### Field Names
+- Must be valid JavaScript property names
+- Case-sensitive
+- No spaces or special characters (except dots)
+
+### Type Names
+- Must be one of the defined types
+- Case-sensitive
+- Parameters must be valid for the type
+
+### Parameter Values
+- Must match expected types
+- Numbers must be valid numbers
+- Booleans must be "true" or "false"
+- Strings must be properly escaped
+
+## Integration Points
+
+### With Search Results
+- Used in SearchResults component
+- Supports filtering and sorting
+- Handles pagination
+- Supports custom layouts
+
+### With Document Display
+- Used in DocumentGridLayout
+- Supports document icons
+- Handles file uploads
+- Manages type selection
+
+### With Selection System
+- Supports single/multi select
+- Range selection with shift-click
+- Selection persistence
+- Selection change callbacks

package/src/features/store/objects/layout/renderers.tsx

@@ -0,0 +1,185 @@
+import dayjs from "dayjs";
+import LocalizedFormat from "dayjs/plugin/localizedFormat";
+import RelativeTime from "dayjs/plugin/relativeTime";
+import { shortId } from "../../../utils";
+import { Eye } from "lucide-react";
+import { Button } from "@vertesia/ui/core";
+dayjs.extend(RelativeTime);
+dayjs.extend(LocalizedFormat);
+
+const renderers: Record<string, (params?: URLSearchParams, onClick?: (id: string) => void) => (value: any, index: number) => React.ReactNode> = {
+    string(params?: URLSearchParams, _onClick?: (id: string) => void) {
+        let transforms: ((value: string) => string)[] = [];
+        if (params) {
+            const slice = params.get("slice");
+            if (slice) {
+                transforms.push((value: string) => value.slice(parseInt(slice)));
+            }
+            const max_length = params.get("max_length");
+            if (max_length) {
+                transforms.push((value: string) => value.slice(0, parseInt(max_length)));
+            }
+            if (params.has("upper")) {
+                transforms.push((value: string) => value.toUpperCase());
+            }
+            if (params.has("lower")) {
+                transforms.push((value: string) => value.toLowerCase());
+            }
+            if (params.has("capitalize")) {
+                transforms.push((value: string) => value[0].toUpperCase() + value.substring(1));
+            }
+            if (params.has("ellipsis")) {
+                transforms.push((value: string) => value + "...");
+            }
+        }
+        return (value: any, index: number) => {
+            let v: string;
+            if (value) {
+                v = String(value);
+                if (transforms.length > 0) {
+                    for (const t of transforms) {
+                        v = t(v);
+                    }
+                }
+            } else {
+                v = "";
+            }
+
+            return <td key={index}>{v}</td>;
+        };
+    },
+
+    fileSize(_params?: URLSearchParams, _onClick?: (id: string) => void) {
+        return (value: any, index: number) => {
+            let fileSize = "";
+            if (value) {
+                const bytes = Number(value);
+                if (!isNaN(bytes)) {
+                    const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
+                    if (bytes === 0) {
+                        fileSize = "0 Bytes";
+                    } else {
+                        const i = Math.floor(Math.log(bytes) / Math.log(1024));
+                        fileSize = `${(bytes / Math.pow(1024, i)).toFixed(2)} ${sizes[i]}`;
+                    }
+                } else {
+                    fileSize = String(value);
+                }
+            }
+            return <td key={index}>{fileSize}</td>;
+        };
+    },
+
+    number(params?: URLSearchParams, _onClick?: (id: string) => void) {
+        let currency: string | undefined;
+        let decimals: string | undefined;
+        if (params) {
+            currency = params.get("currency") || undefined;
+            decimals = params.get("decimals") || undefined;
+        }
+
+        const digits = decimals ? parseInt(decimals) : 2;
+
+        return (value: any, index: number) => {
+            let v = new Intl.NumberFormat("en-US", {
+                style: currency ? "currency" : "decimal",
+                currency,
+                maximumFractionDigits: digits,
+            }).format(value);
+            return <td key={index}>{v}</td>;
+        };
+    },
+    objectId(params?: URLSearchParams, onClick?: (id: string) => void) {
+        let transforms: ((value: string) => string)[] = [];
+        let hasSlice = false;
+        if (params) {
+            const slice = params.get("slice");
+            if (slice) {
+                hasSlice = true;
+                transforms.push((value) => value.slice(parseInt(slice)));
+            }
+        }
+        return (value: any, index: number) => {
+            const displayValue = transforms.reduce((v, t) => t(v), value.id);
+            return (
+                <td key={index} className="flex justify-between items-center gap-2">
+                    {hasSlice ? '~' : ''}{displayValue}
+                    <Button
+                        variant="ghost"
+                        alt="Preview Object"
+                        onClick={(e) => {
+                            e.stopPropagation();
+                            onClick?.(value.id);
+                        }}
+                    >
+                        <Eye className="size-4" />
+                    </Button>
+                </td>
+            );
+        };
+    },
+    objectName(params?: URLSearchParams, _onClick?: (id: string) => void) {
+        let title = "title";
+        if (params) {
+            title = params.get("title") || "title";
+        }
+        return (value: any, index: number) => {
+            return (
+                <td key={index}>
+                    {value.properties?.[title] || value.name || shortId(value.id)}
+                </td>
+            );
+        };
+    },
+    // objectLink - same implementation as objectId but defaults to slice=-7
+    objectLink(_params?: URLSearchParams, onClick?: (id: string) => void) {
+        const transforms: ((value: string) => string)[] = [];
+        const hasSlice = true;
+        transforms.push((value) => value.slice(-7));
+
+        return (value: any, index: number) => {
+            const displayValue = transforms.reduce((v, t) => t(v), value.id);
+            return (
+                <td key={index} className="flex justify-between items-center gap-2 max-w-48">
+                    {hasSlice ? "~" : ""}{displayValue}
+                    <Button
+                        variant="ghost"
+                        alt="Preview Object"
+                        onClick={(e) => {
+                            e.stopPropagation();
+                            onClick?.(value.id);
+                        }}
+                    >
+                        <Eye className="size-4" />
+                    </Button>
+                </td>
+            );
+        };
+    },
+    typeLink(_params?: URLSearchParams, _onClick?: (id: string) => void) {
+        return (value: any, index: number) => {
+            return <td key={index}>{value?.name || "n/a"}</td>;
+        };
+    },
+    date(params?: URLSearchParams, _onClick?: (id: string) => void) {
+        let method = "format";
+        let arg: string | undefined = "LLL";
+        if (params) {
+            const localized = params.get("localized");
+            if (localized) {
+                arg = localized;
+            } else {
+                const relative = params.get("relative");
+                if (relative) {
+                    method = relative; // fromNow or toNow
+                    arg = undefined;
+                }
+            }
+        }
+        return (value: any, index: number) => {
+            return <td key={index}>{(dayjs(value) as any)[method](arg)}</td>;
+        };
+    },
+};
+
+export default renderers;

package/src/features/store/objects/search/DocumentSearchContext.ts

@@ -0,0 +1,215 @@
+import { createContext, useContext } from 'react';
+
+import { SharedState, useWatchSharedState } from '@vertesia/ui/core';
+import { ComputeFacetsResponse, ZenoClient } from '@vertesia/client';
+import { ComplexSearchPayload, ComplexSearchQuery, ComputeObjectFacetPayload, ContentObjectItem, FacetBucket, FacetSpec, ObjectSearchQuery } from '@vertesia/common';
+import { SearchInterface } from '@vertesia/ui/features'
+
+interface DocumentSearchResult {
+    objects: ContentObjectItem[],
+    error?: Error;
+    isLoading: boolean;
+    hasMore?: boolean;
+}
+
+
+export class DocumentSearch implements SearchInterface {
+
+    collectionId?: string;
+    facets = new SharedState<ComputeFacetsResponse>({});
+    result = new SharedState<DocumentSearchResult>({ objects: [], isLoading: false });
+
+    facetSpecs: FacetSpec[] = [];
+    query: ComplexSearchQuery = {};
+
+    constructor(public client: ZenoClient, public limit = 100) { }
+
+    withFacets(facets: FacetSpec[]) {
+        this.facetSpecs = facets;
+        return this;
+    }
+
+    get objects() {
+        return this.result.value.objects;
+    }
+
+    get error() {
+        return this.result.value.error;
+    }
+
+    get isRunning(): boolean {
+        return this.result.value.isLoading;
+    }
+
+    get hasMore(): boolean {
+        return this.result.value.hasMore || false;
+    }
+
+    getFilterValue(name: string) {
+        return (this.query as any)[name];
+    }
+
+    setFilterValue(name: string, value: any) {
+        (this.query as any)[name] = value;
+        // search now
+        this.search();
+    }
+
+    setDefaultKeys(keys: any[]) {
+        void keys;
+    }
+
+    clearFilters(autoSearch: boolean = true) {
+        // Preserve search-related fields when clearing filters
+        const { parent, full_text, vector, weights, score_aggregation, dynamic_scaling, limit, all_revisions } = this.query;
+        this.query = {
+            parent,
+            ...(full_text !== undefined && { full_text }),
+            ...(vector !== undefined && { vector }),
+            ...(weights !== undefined && { weights }),
+            ...(score_aggregation !== undefined && { score_aggregation }),
+            ...(dynamic_scaling !== undefined && { dynamic_scaling }),
+            ...(all_revisions !== undefined && { all_revisions }),
+            ...(limit !== undefined && { limit })
+        };
+
+        if (autoSearch) {
+            this.search();
+        }
+    }
+
+    getFacetBuckets(name: string): FacetBucket[] {
+        return (this.facets.value as any)[name]?.buckets || [];
+    }
+
+    resetFacets() {
+        this.query = {};
+    }
+
+    reset(isLoading = false) {
+        this.result.value = {
+            objects: [],
+            isLoading,
+            hasMore: true
+        };
+    }
+
+    _updateRunningState(value: boolean) {
+        const prev = this.result.value;
+        this.result.value = {
+            objects: prev.objects,
+            isLoading: value,
+            error: prev.error,
+            hasMore: prev.hasMore
+        }
+    }
+
+    _searchRequest(query: ComplexSearchQuery, limit: number, offset: number, includeFacets: boolean = true) {
+        const payload: ComplexSearchPayload = {
+            limit,
+            offset,
+            query,
+            facets: includeFacets ? this.facetSpecs : undefined
+        };
+
+        const request = this.collectionId ?
+            this.client.collections.searchMembers(this.collectionId, payload)
+            : this.client.objects.search(payload);
+            
+        return request;
+    }
+
+    _facetsRequest() {
+        const payload: ComputeObjectFacetPayload = { facets: this.facetSpecs, query: this.query }
+        return this.collectionId ?
+            this.client.collections.computeFacets(this.collectionId, payload)
+            : this.client.objects.computeFacets(payload);
+    }
+
+    computeFacets(_query: ObjectSearchQuery) {
+        this._facetsRequest().then((facets) => {
+            this.facets.value = facets;
+        });
+    }
+
+    _search(loadMore = false, noFacets = false) {
+        if (this.isRunning && loadMore) { // avoid searching when a search is pending, but allow initial search
+            return Promise.resolve(false);
+        }
+        this.result.value = {
+            isLoading: true,
+            objects: loadMore ? this.objects : [],
+            hasMore: loadMore ? this.result.value.hasMore : true
+        }
+        const limit = this.limit;
+        const offset = loadMore ? this.objects.length : 0;
+        return this._searchRequest(this.query, limit, offset, !noFacets).then(async (res) => {
+            // Handle the new format with results and facets
+            const results = res.results || [];
+            const facets = res.facets || {};
+
+            this.result.value = {
+                isLoading: false,
+                objects: loadMore ? this.objects.concat(results) : results,
+                hasMore: results.length === limit
+            }
+
+            // Update facets if they were requested and returned
+            if (!noFacets && facets && Object.keys(facets).length > 0) {
+                this.facets.value = facets;
+            }
+
+            return true;
+        }).catch((err) => {
+            this.result.value = {
+                error: err,
+                isLoading: false,
+                objects: this.objects,
+                hasMore: this.result.value.hasMore
+            }
+            throw err;
+        })
+    }
+
+    search(noFacets = false) {
+        // Allow initial search even if isLoading is true (for initial page load)
+        if (this.isRunning && this.objects.length > 0) {
+            return Promise.resolve(false);
+        }
+        return this._search(false, noFacets);
+    }
+
+    loadMore(noFacets = false) {
+        if (this.isRunning || !this.hasMore) return Promise.resolve(false);
+        if (this.query.vector) return Promise.resolve(false); //Load more not supported on vector queries
+        if (this.objects.length > 0) {
+            noFacets = true; //Only reload facets on loadMore if there are no results.
+        }
+        return this._search(true, noFacets);
+    }
+}
+
+const DocumentSearchContext = createContext<DocumentSearch | undefined>(undefined);
+
+export function useDocumentSearch() {
+    return useContext(DocumentSearchContext)!;
+}
+
+export function useWatchDocumentSearchFacets() {
+    return useWatchSharedState(useDocumentSearch().facets);
+}
+
+export function useWatchDocumentSearchResult() {
+    const search = useDocumentSearch();
+    const result = useWatchSharedState(search.result);
+    return { ...result, search };
+}
+
+export function useDocumentSearchCount() {
+    const search = useDocumentSearch();
+    const result = useWatchSharedState(search.facets);
+    return result.total;
+}
+
+
+export { DocumentSearchContext as SearchContext };

package/src/features/store/objects/search/DocumentSearchProvider.tsx

@@ -0,0 +1,50 @@
+import { useUserSession } from "@vertesia/ui/session";
+import { FacetSpec } from "@vertesia/common";
+import React, { useMemo } from "react";
+import { DocumentSearch, SearchContext } from "./DocumentSearchContext";
+
+interface DocumentSearchProviderProps {
+    children: React.ReactNode;
+    limit?: number;
+    typeId?: string;
+    parent?: string;
+    facets?: FacetSpec[];
+    collectionId?: string;
+    name?: string;
+}
+export function DocumentSearchProvider({ children, limit, parent, typeId, facets, name, collectionId }: DocumentSearchProviderProps) {
+    const { store } = useUserSession();
+    const search = useMemo(() => {
+        let facetSpecs: FacetSpec[];
+        if (facets) {
+            facetSpecs = facets;
+        } else {
+            facetSpecs = [
+                {
+                    name: 'status',
+                    field: 'status'
+                },
+                {
+                    name: 'location',
+                    field: 'location'
+                }
+            ]
+            if (!typeId) {
+                facetSpecs.unshift({
+                    name: 'type',
+                    field: 'type'
+                })
+            }
+        }
+        const search = new DocumentSearch(store, limit).withFacets(facetSpecs);
+        search.collectionId = collectionId;
+        search.query.type = typeId;
+        search.query.parent = parent;
+        search.query.name = name;
+        return search;
+    }, [typeId, limit, collectionId]);
+
+    return (
+        <SearchContext.Provider value={search}>{children}</SearchContext.Provider>
+    )
+}

package/src/features/store/objects/search/index.ts

@@ -0,0 +1,2 @@
+export * from "./DocumentSearchContext"
+export * from "./DocumentSearchProvider"