@pitcher/js-api 1.26.1 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/js-api",
-  "version": "1.26.1",
+  "version": "1.27.0",
   "type": "module",
   "main": "js-api.umd.min.js",
   "module": "js-api.esm.js",

package/{lib → src/lib}/apps/browser/appTypes.d.ts

@@ -1,6 +1,6 @@
 import { MetadataTemplateFieldTypeEnum } from '../../../types/openapi';
 import { AppName } from './stores/app';
-import { FolderItemsFetcher, FolderCreator, FolderUpdater, FolderDeleter, FileCreator, FileUpdater, FileOpener, FileFetcher, FileListFetcher, ItemsMover, ItemsCopier, FileCopier, SelectDeviceFile, FileDeleter, FolderLister, DistributionGroupsFetcher, DistributionGroupsAssigner } from './stores/api';
+import { FolderItemsFetcher, FolderCreator, FolderUpdater, FolderDeleter, FileCreator, FileUpdater, FileOpener, FileFetcher, FileListFetcher, ItemsMover, ItemsReorder, ItemsCopier, FileCopier, SelectDeviceFile, FileDeleter, FolderLister, DistributionGroupsFetcher, DistributionGroupsAssigner } from './stores/api';
 export interface BrowserCustomFilterComponent {
     type: MetadataTemplateFieldTypeEnum;
     name: string;
@@ -23,6 +23,7 @@ export interface BrowserAppProps {
     onFileFetch: FileFetcher;
     onFilesList: FileListFetcher;
     onItemsMove?: ItemsMover;
+    onItemsReorder?: ItemsReorder;
     onItemsCopy?: ItemsCopier;
     /**
      * Per-upload fan-out: after the initial upload creates a new file in

package/{lib → src/lib}/apps/browser/stores/api.d.ts

@@ -46,6 +46,11 @@ type ItemsMoverItem = {
     type: 'file' | 'folder';
 };
 type ItemsMover = (folderId: Folder['id'], items: ItemsMoverItem[]) => Promise<FolderRetrieve>;
+type ItemsReorderItem = {
+    id: File['id'] | Folder['id'];
+    type: 'file' | 'folder';
+};
+type ItemsReorder = (folderId: Folder['id'], items: ItemsReorderItem[]) => Promise<void>;
 type ItemsCopierItem = {
     id: File['id'];
     type: 'file';
@@ -71,7 +76,7 @@ declare function setSearchMetadataFilters(filters: Record<string, any>): void;
 declare function setFilteredItems(items: FolderFileWithFolder[]): void;
 declare function onUpsertFolder(name: string, initialName?: string): Promise<void>;
 declare function clearTimeouts(): void;
-declare function init({ onFolderFetch, onFolderCreate, onFolderUpdate, onFolderDelete, onFoldersDelete, onFileCreate, onFileUpdate, onFileOpen, onFileDelete, onFilesDelete, onFileFetch, onFilesList, onItemsMove, onItemsCopy, onFileCopy, onSelectDeviceFile, onFolderList, onFetchDistributionGroups, onAssignDistributionGroups, distributionGroupsManageUrl, }: {
+declare function init({ onFolderFetch, onFolderCreate, onFolderUpdate, onFolderDelete, onFoldersDelete, onFileCreate, onFileUpdate, onFileOpen, onFileDelete, onFilesDelete, onFileFetch, onFilesList, onItemsMove, onItemsReorder, onItemsCopy, onFileCopy, onSelectDeviceFile, onFolderList, onFetchDistributionGroups, onAssignDistributionGroups, distributionGroupsManageUrl, }: {
     onFolderFetch: FolderItemsFetcher;
     onFolderCreate?: FolderCreator;
     onFolderUpdate?: FolderUpdater;
@@ -85,6 +90,7 @@ declare function init({ onFolderFetch, onFolderCreate, onFolderUpdate, onFolderD
     onFileFetch: FileFetcher;
     onFilesList: FileListFetcher;
     onItemsMove?: ItemsMover;
+    onItemsReorder?: ItemsReorder;
     onItemsCopy?: ItemsCopier;
     onFileCopy?: FileCopier;
     onSelectDeviceFile?: SelectDeviceFile;
@@ -93,7 +99,7 @@ declare function init({ onFolderFetch, onFolderCreate, onFolderUpdate, onFolderD
     onAssignDistributionGroups?: DistributionGroupsAssigner;
     distributionGroupsManageUrl?: string;
 }): void;
-export type { FolderItemsFetcher, FolderCreator, FolderUpdater, FolderDeleter, FoldersDeleter, FileCreator, FileUpdater, FileOpener, FileDeleter, FilesDeleter, FileFetcher, FileListFetcher, ItemsMoverItem, ItemsMover, ItemsCopierItem, ItemsCopier, FileCopier, CompactFile, CompactFolder, SelectDeviceFile, FolderLister, DistributionGroupsFetcher, DistributionGroupsAssigner, };
+export type { FolderItemsFetcher, FolderCreator, FolderUpdater, FolderDeleter, FoldersDeleter, FileCreator, FileUpdater, FileOpener, FileDeleter, FilesDeleter, FileFetcher, FileListFetcher, ItemsMoverItem, ItemsMover, ItemsReorderItem, ItemsReorder, ItemsCopierItem, ItemsCopier, FileCopier, CompactFile, CompactFolder, SelectDeviceFile, FolderLister, DistributionGroupsFetcher, DistributionGroupsAssigner, };
 declare const _default: () => {
     state: {
         readonly fileOpener: FileOpener | null;
@@ -112,6 +118,7 @@ declare const _default: () => {
         readonly filesFoldersDeleter: FilesFoldersDeleter | null;
         readonly selectDeviceFile?: (SelectDeviceFile | null) | undefined;
         readonly itemsMover: ItemsMover | null;
+        readonly itemsReorder: ItemsReorder | null;
         readonly itemsCopier: ItemsCopier | null;
         readonly fileCopier: FileCopier | null;
         readonly folderLister: FolderLister | null;
@@ -138,6 +145,7 @@ declare const _default: () => {
             readonly id: string;
             readonly name: string;
             readonly thumbnail_url: string | null;
+            readonly order?: number | null | undefined;
             readonly folders_count: number;
             readonly files_count: number;
             readonly available_files_count: number;
@@ -252,6 +260,7 @@ declare const _default: () => {
         readonly selectedFolder: {
             readonly id: string;
             readonly name: string;
+            readonly instance_id: string;
             readonly content_type: string;
             readonly access_type?: import('../../../../types/openapi').AccessTypeEnum | undefined;
             readonly rules?: readonly {
@@ -270,6 +279,7 @@ declare const _default: () => {
                 readonly id: string;
                 readonly name: string;
                 readonly thumbnail_url: string | null;
+                readonly order?: number | null | undefined;
                 readonly folders_count: number;
                 readonly files_count: number;
                 readonly available_files_count: number;
@@ -283,6 +293,7 @@ declare const _default: () => {
                 readonly id: string;
                 readonly name: string;
                 readonly thumbnail_url: string | null;
+                readonly order?: number | null | undefined;
                 readonly folders_count: number;
                 readonly files_count: number;
                 readonly available_files_count: number;
@@ -358,6 +369,7 @@ declare const _default: () => {
             readonly id: string;
             readonly name: string;
             readonly thumbnail_url: string | null;
+            readonly order?: number | null | undefined;
             readonly folders_count: number;
             readonly files_count: number;
             readonly available_files_count: number;
@@ -475,6 +487,7 @@ declare const _default: () => {
             fileListFetcher: null;
             filesFoldersDeleter: null;
             itemsMover: null;
+            itemsReorder: null;
             itemsCopier: null;
             fileCopier: null;
             folderLister: null;
@@ -526,6 +539,7 @@ declare const _default: () => {
             filesFoldersDeleter: FilesFoldersDeleter | null;
             selectDeviceFile?: (SelectDeviceFile | null) | undefined;
             itemsMover: ItemsMover | null;
+            itemsReorder: ItemsReorder | null;
             itemsCopier: ItemsCopier | null;
             fileCopier: FileCopier | null;
             folderLister: FolderLister | null;
@@ -552,6 +566,7 @@ declare const _default: () => {
                 id: string;
                 name: string;
                 thumbnail_url: string | null;
+                order?: number | null | undefined;
                 folders_count: number;
                 files_count: number;
                 available_files_count: number;
@@ -658,6 +673,7 @@ declare const _default: () => {
             selectedFolder: {
                 readonly id: string;
                 name: string;
+                readonly instance_id: string;
                 readonly content_type: string;
                 access_type?: import('../../../../types/openapi').AccessTypeEnum | undefined;
                 rules?: {
@@ -676,6 +692,7 @@ declare const _default: () => {
                     readonly id: string;
                     name: string;
                     readonly thumbnail_url: string | null;
+                    order?: number | null | undefined;
                     readonly folders_count: number;
                     readonly files_count: number;
                     readonly available_files_count: number;
@@ -689,6 +706,7 @@ declare const _default: () => {
                     readonly id: string;
                     name: string;
                     readonly thumbnail_url: string | null;
+                    order?: number | null | undefined;
                     readonly folders_count: number;
                     readonly files_count: number;
                     readonly available_files_count: number;
@@ -762,6 +780,7 @@ declare const _default: () => {
                 readonly id: string;
                 name: string;
                 readonly thumbnail_url: string | null;
+                order?: number | null | undefined;
                 readonly folders_count: number;
                 readonly files_count: number;
                 readonly available_files_count: number;
@@ -835,6 +854,7 @@ declare const _default: () => {
             fileListFetcher: null;
             filesFoldersDeleter: null;
             itemsMover: null;
+            itemsReorder: null;
             itemsCopier: null;
             fileCopier: null;
             folderLister: null;

package/{lib → src/lib}/apps/browser/stores/app.d.ts

@@ -6,7 +6,7 @@ import { InstanceSettings } from '../../../types/instanceSettings.types';
 export type AppName = 'admin' | 'impact';
 export type AppCurrentState = 'browse' | 'create-folder' | 'upload-files' | 'update-folder' | 'update-file' | 'batch-move' | 'batch-copy';
 export type BrowserSectionType = 'all' | 'trash' | 'rep-uploads';
-export type SortOption = 'nameAsc' | 'nameDesc' | 'modifiedAsc' | 'modifiedDesc';
+export type SortOption = 'nameAsc' | 'nameDesc' | 'modifiedAsc' | 'modifiedDesc' | 'custom';
 export type StateSelectedItem = Partial<File | Folder> & {
     type: string | null | undefined;
     thumbnail_url: string | null | undefined;
@@ -34,12 +34,17 @@ export default function (): {
     selectAndOpenContentPanel(item: ViewCompactFileFolder): void;
     setCurrentState(stateName: AppCurrentState, itemId?: Folder["id"] | File["id"]): void;
     clearInlineEditingItem(): void;
+    clearManualSortOverride(): void;
     appName: Ref<AppName | "">;
     currentState: Ref<AppCurrentState>;
     selectedItemIds: Ref<SelectedItemId[]>;
     selectedSection: Ref<BrowserSectionType>;
     selectedView: Ref<View>;
     selectedSortOption: Ref<SortOption>;
+    manualSortOverride: Ref<SortOption | null>;
+    customOrderEnabled: ComputedRef<boolean>;
+    folderHasCustomOrder: ComputedRef<boolean>;
+    effectiveSortOption: ComputedRef<SortOption>;
     search: Ref<string>;
     displayedFiles: ComputedRef<ViewCompactFile[]>;
     displayedFolders: ComputedRef<ViewCompactFolder[]>;

package/src/lib/apps/browser/util/sortOrder.d.ts

@@ -0,0 +1,36 @@
+import { ViewCompactFileFolder } from '../../../types/files';
+export type ReorderItem = {
+    id: string;
+    type: 'file' | 'folder';
+};
+/**
+ * Resolve the sort actually applied in the browser: an explicit per-visit choice
+ * wins; otherwise a folder with a custom order defaults to it; otherwise the
+ * user's saved sort. Kept pure (string in/out) so it's unit-testable and free of
+ * a dependency on the store's SortOption type.
+ */
+export declare function resolveSortOption(manualOverride: string | null, folderHasCustomOrder: boolean, savedDefault: string): string;
+/**
+ * The manual custom-sort position of a browser item, if one has been set.
+ * Folders carry it on `order`; files under `metadata.pitcher.order`.
+ */
+export declare function getItemOrder(item: ViewCompactFileFolder): number | undefined;
+/**
+ * Order a mixed list of files and folders by their custom position, falling back
+ * to alphabetical for items without one (and to break ties).
+ */
+export declare function sortByCustomOrder<T extends ViewCompactFileFolder>(items: T[]): T[];
+/**
+ * Move every selected item to the top or bottom of the list, consolidating a
+ * non-contiguous selection into a single contiguous block while preserving the
+ * items' relative order (matches the "Send to top / Send to bottom" spec).
+ */
+export declare function moveSelectedTo<T extends ViewCompactFileFolder>(items: T[], selectedIds: ReadonlyArray<string | number>, position: 'top' | 'bottom'): T[];
+/**
+ * Move a single dragged item directly above or below a target item (single-item
+ * drag-and-drop reorder). Returns the input unchanged when the drag is a no-op
+ * or references an item that is not in the list.
+ */
+export declare function moveItemRelativeTo<T extends ViewCompactFileFolder>(items: T[], draggedId: string | number, targetId: string | number, position: 'above' | 'below'): T[];
+/** Project a displayed list into the `{ id, type }` payload the reorder API expects. */
+export declare function toReorderItems(items: ViewCompactFileFolder[]): ReorderItem[];

package/{lib → src/lib}/apps/canvas-builder/components/ui/DataCharts/types.d.ts

@@ -119,19 +119,25 @@ export interface BulkDataMapping {
     source_path: string;
     label_field: string;
     value_field?: string;
+    min_field?: string;
+    max_field?: string;
     x_field?: string;
     y_field?: string;
     r_field?: string;
 }
 export type BulkDataResult = {
     labels: string[];
-    values: (number | {
+    values: (number | [number, number] | {
         x: number;
         y: number;
         r?: number;
         originalR?: number;
     })[];
 };
+export declare function isFloatingBarMapping(mapping?: BulkDataMapping | null): boolean;
+export declare function floatingBarDatasetOptions(): {
+    grouped: false;
+};
 export declare function normalizeRValues(values: Array<{
     x: number;
     y: number;

package/{lib → src/lib}/apps/canvas-builder/components/ui/DynamicContent/useDynamicContent.d.ts

@@ -40,6 +40,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
             readonly template: {
                 readonly id: string;
                 name: string;
+                readonly tags?: Array<string> | undefined;
             };
             readonly sections: {
                 readonly id: string;
@@ -49,6 +50,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
                 metadata?: Record<string, any> | undefined;
                 is_draft: boolean;
             }[];
+            readonly section_ids?: Array<string> | undefined;
             readonly shared_link: {
                 readonly url: string;
                 short_url?: string | null | undefined;
@@ -106,6 +108,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
             readonly template: {
                 readonly id: string;
                 name: string;
+                readonly tags?: Array<string> | undefined;
             };
             readonly sections: {
                 readonly id: string;
@@ -115,6 +118,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
                 metadata?: Record<string, any> | undefined;
                 is_draft: boolean;
             }[];
+            readonly section_ids?: Array<string> | undefined;
             readonly shared_link: {
                 readonly url: string;
                 short_url?: string | null | undefined;
@@ -325,6 +329,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
         readonly template: {
             readonly id: string;
             name: string;
+            readonly tags?: Array<string> | undefined;
         };
         readonly sections: {
             readonly id: string;
@@ -334,6 +339,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
             metadata?: Record<string, any> | undefined;
             is_draft: boolean;
         }[];
+        readonly section_ids?: Array<string> | undefined;
         readonly shared_link: {
             readonly url: string;
             short_url?: string | null | undefined;
@@ -388,6 +394,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
         readonly template: {
             readonly id: string;
             name: string;
+            readonly tags?: Array<string> | undefined;
         };
         readonly sections: {
             readonly id: string;
@@ -397,6 +404,7 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
             metadata?: Record<string, any> | undefined;
             is_draft: boolean;
         }[];
+        readonly section_ids?: Array<string> | undefined;
         readonly shared_link: {
             readonly url: string;
             short_url?: string | null | undefined;
@@ -431,6 +439,8 @@ export declare function useDynamicContent(hasConfig?: Ref<boolean> | ComputedRef
     }> & Omit<Map<string, CanvasRetrieve>, keyof Map<any, any>>)>;
     hasSectionCached: (sectionId: string) => boolean;
     getCachedSection: (sectionId: string) => CanvasRetrieve | undefined;
-    fetchDynamicContent: (config: DynamicContentProps) => Promise<void>;
+    fetchDynamicContent: (config: DynamicContentProps, options?: {
+        silent?: boolean;
+    }) => Promise<void>;
     fetchSectionContent: (sectionId: string) => Promise<CanvasRetrieve | null>;
 };

package/src/lib/apps/canvas-builder/composables/lazySections.d.ts

@@ -0,0 +1,53 @@
+import { CanvasSection } from '../../../../types/openapi';
+/**
+ * Opt-in lazy section loading — client-side hydration engine.
+ *
+ * When a canvas is fetched as a "shell" (`?lazy_sections=true` + the
+ * `lazy_load_sections` setting), it carries ordered `section_ids` instead of the
+ * heavy inline `sections`. This engine drains those IDs through the batch
+ * endpoint progressively (bounded batches, capped concurrency) and feeds the
+ * hydrated bodies back so the renderer fills in as they arrive.
+ *
+ * It is a PURE async queue — no Vue, no network knowledge — so it is unit
+ * testable in isolation and reused unchanged by `useCanvas`. It is completely
+ * dormant unless `start()` is called with a non-empty ID list, which only
+ * happens for a shell canvas; the legacy fully-expanded path never touches it.
+ */
+/** Server-side `MAX_BATCH` in Django `sections_by_ids` / next-core by-ids route. */
+export declare const MAX_SECTIONS_PER_BATCH = 100;
+export interface LazySectionLoaderOptions {
+    /** Fetch the bodies for a slice of section IDs (≤ MAX_SECTIONS_PER_BATCH). */
+    fetchBatch: (sectionIds: string[]) => Promise<CanvasSection[]>;
+    /** Called with each hydrated batch as it resolves (append into the canvas). */
+    onSections: (sections: CanvasSection[]) => void;
+    /** Per-batch error sink. A failed batch is isolated; the drain continues. */
+    onError?: (error: unknown, sectionIds: string[]) => void;
+    /** Sections per request. Clamped to [1, MAX_SECTIONS_PER_BATCH]. Default 50. */
+    batchSize?: number;
+    /** Max in-flight batches. Default 2. */
+    concurrency?: number;
+}
+export interface LazySectionLoader {
+    /**
+     * Begin draining `allSectionIds`, skipping any already in `loadedSectionIds`.
+     * Order is preserved (content order = reading order, top-down). Idempotent
+     * per ID — an ID already queued/in-flight/done is never enqueued twice.
+     */
+    start(allSectionIds: string[], loadedSectionIds?: Iterable<string>): void;
+    /**
+     * Move the given IDs to the front of the remaining queue (e.g. the section a
+     * deep-link / the rep's current page points at), so they hydrate first.
+     * Unknown or already-loaded IDs are ignored. A section whose background batch
+     * previously FAILED is revived here for an on-demand retry (bounded), so
+     * navigating onto a transiently-failed section fetches it instead of leaving
+     * it blank.
+     */
+    prioritize(sectionIds: string[]): void;
+    /** Resolves once the queue is fully drained (all batches settled). */
+    ensureAll(): Promise<void>;
+    /** Cancel everything in flight and clear the queue (new deck load). */
+    reset(): void;
+    /** Remaining queued IDs not yet hydrated. */
+    pendingCount(): number;
+}
+export declare function createLazySectionLoader(options: LazySectionLoaderOptions): LazySectionLoader;