orgnote-api 0.41.15 → 0.41.17

package/api.d.ts

@@ -27,9 +27,22 @@ import { CronStoreDefinition } from './models/cron-store.js';
 import { GitStoreDefinition } from './models/git-store.js';
 import { ExtensionRegistryStoreDefinition } from './models/extension-registry-store.js';
 import { parseToml, stringifyToml } from './utils/index.js';
+/** @internal */
 type WithNodeType<T> = {
     nodeType: NodeType;
 } & T;
+/**
+ * Discriminated union describing an editor widget registration.
+ *
+ * Use {@link WidgetType} to choose the variant:
+ * - `Inline` — decorates a single inline node (mark, replace, or widget decoration).
+ * - `Multiline` — replaces an entire block node with a custom view.
+ * - `LineClass` — attaches a CSS class to a line containing the target node.
+ *
+ * @see {@link InlineEmbeddedWidget}
+ * @see {@link MultilineEmbeddedWidget}
+ * @see {@link OrgLineClass}
+ */
 export type WidgetMeta = ({
     type: WidgetType.Inline;
 } & WithNodeType<InlineEmbeddedWidget>) | ({
@@ -37,41 +50,228 @@ export type WidgetMeta = ({
 } & WithNodeType<MultilineEmbeddedWidget>) | ({
     type: WidgetType.LineClass;
 } & WithNodeType<OrgLineClass>);
+/**
+ * Low-level infrastructure layer: data repositories and real-time WebSocket connection.
+ *
+ * Prefer higher-level stores from {@link OrgNoteApi.core} unless you need
+ * direct database or socket access.
+ */
 export type Infrastructure = Repositories & {
     websocket: WebSocketClient;
 };
+/**
+ * Main API facade provided to every OrgNote extension.
+ *
+ * Received as the sole argument of the {@link Extension.onMounted} lifecycle hook.
+ * Groups all available services into four namespaces:
+ * - `core` — application stores (commands, files, encryption, sync, buffers)
+ * - `utils` — platform helpers, CSS manipulation, clipboard, logging, parsers
+ * - `ui` — modals, sidebars, themes, fonts, screen detection
+ * - `vue` — Vue Router instance
+ *
+ * @example
+ * ```typescript
+ * import type { Extension, OrgNoteApi } from 'orgnote-api';
+ *
+ * const extension: Extension = {
+ *   async onMounted(api: OrgNoteApi) {
+ *     const commands = api.core.useCommands();
+ *     commands.add({
+ *       command: 'hello-world',
+ *       title: 'Hello World',
+ *       handler: () => {
+ *         const notifications = api.core.useNotifications();
+ *         notifications.notify({ message: 'Hello from extension!' });
+ *       },
+ *     });
+ *   },
+ *
+ *   async onUnmounted(api: OrgNoteApi) {
+ *     // cleanup is automatic for commands registered via `add`
+ *   },
+ * };
+ *
+ * export default extension;
+ * ```
+ */
 export interface OrgNoteApi {
     [key: string]: unknown;
+    /**
+     * Low-level infrastructure: data repositories and WebSocket client.
+     *
+     * Provides direct access to persistence layer ({@link Repositories}) and
+     * the real-time {@link WebSocketClient}. For most use cases prefer
+     * the higher-level stores in {@link OrgNoteApi.core}.
+     */
     infrastructure: Infrastructure;
+    /**
+     * Core application stores — the primary way extensions interact with OrgNote.
+     *
+     * Each property is a [Pinia](https://pinia.vuejs.org/) store factory.
+     * Call it to obtain a reactive store instance:
+     * ```typescript
+     * const commands = api.core.useCommands();
+     * const fs = api.core.useFileSystem();
+     * ```
+     */
     core: {
+        /**
+         * Register, remove, and execute commands (keyboard shortcuts, command palette actions).
+         *
+         * @example
+         * ```typescript
+         * const commands = api.core.useCommands();
+         * commands.add({
+         *   command: 'my-ext.greet',
+         *   title: 'Greet User',
+         *   handler: () => console.log('Hello!'),
+         * });
+         * await commands.execute('my-ext.greet');
+         * ```
+         */
         useCommands: CommandsStoreDefinition;
+        /**
+         * Manage command groups — logical collections of commands
+         * displayed together in the UI (e.g. "Editor", "Navigation").
+         */
         useCommandsGroup: CommandsGroupStoreDefinition;
+        /**
+         * Install, enable, disable, and delete extensions at runtime.
+         * Also provides the list of currently loaded extensions.
+         */
         useExtensions: ExtensionStoreDefinition;
+        /**
+         * Virtual file system abstraction (read, write, delete, mkdir, etc.).
+         * Works across platforms via [Capacitor Filesystem](https://capacitorjs.com/docs/apis/filesystem) under the hood.
+         *
+         * @example
+         * ```typescript
+         * const fs = api.core.useFileSystem();
+         * const content = await fs.readFile(['notes', 'todo.org'], 'utf8');
+         * await fs.writeFile(['notes', 'new.org'], '* New note');
+         * ```
+         */
         useFileSystem: FileSystemStoreDefinition;
         useFileWatcher: FileWatcherStoreDefinition;
+        /**
+         * Encrypt and decrypt text content using [OpenPGP.js](https://openpgpjs.org/).
+         * Used internally for end-to-end encrypted notes.
+         */
         useEncryption: EncryptionStoreDefinition;
+        /**
+         * Read and manage user-facing application settings.
+         * Also handles API token lifecycle (create, list, revoke).
+         */
         useSettings: SettingsStoreDefinition;
         useConfig: ConfigStoreDefinition;
+        /**
+         * Access the [Quasar](https://quasar.dev/) framework globals ($q).
+         * Useful for Quasar-specific features like `$q.dark`, `$q.screen`, etc.
+         */
         useQuasar: () => QVueGlobals;
+        /**
+         * Open a searchable completion menu (command palette style).
+         * Supports custom item lists, filtering, and keyboard navigation.
+         *
+         * @example
+         * ```typescript
+         * const completion = api.core.useCompletion();
+         * const selected = await completion.open({
+         *   items: ['Apple', 'Banana', 'Cherry'],
+         *   itemLabel: (item) => item,
+         * });
+         * ```
+         */
         useCompletion: CompletionStoreDefinition;
         usePane: PaneStoreDefinition;
+        /**
+         * Manage layout tree structure (split, merge, resize panes).
+         * This is the primary coordinator for all pane-related operations.
+         */
         useLayout: LayoutStoreDefinition;
+        /**
+         * High-level file system manager that orchestrates file operations
+         * with metadata, indexing, and synchronization awareness.
+         */
         useFileSystemManager: FileSystemManagerStoreDefinition;
+        /**
+         * File management operations: open, create, rename, delete notes
+         * with full UI integration (buffer creation, navigation).
+         */
         useFileManager: FileManagerStoreDefinition;
         useBufferViewer: BufferViewerStoreDefinition;
+        /**
+         * Show toast and persistent notifications to the user.
+         *
+         * @example
+         * ```typescript
+         * const notifications = api.core.useNotifications();
+         * notifications.notify({
+         *   message: 'Note saved successfully',
+         *   type: 'positive',
+         * });
+         * ```
+         */
         useNotifications: NotificationsStoreDefinition;
+        /**
+         * Manage open buffers (documents loaded in memory).
+         * Buffers are identified by URI and support dirty-state tracking.
+         */
         useBuffers: BufferStoreDefinition;
+        /**
+         * Register and resolve buffer content providers.
+         * Providers define how different URI schemes load their content.
+         */
         useBufferProviders: BufferProviderStoreDefinition;
         useSystemInfo: UseSystemInfo;
         useLog: LogStoreDefinition;
+        /**
+         * Background task queue with concurrency control, locking, and retry.
+         * Used for long-running operations like sync and bulk file processing.
+         */
         useQueue: QueueStoreDefinition;
+        /**
+         * Schedule recurring tasks (cron-like).
+         * Tasks persist across sessions and run in the background.
+         */
         useCron: CronStoreDefinition;
         useGit: GitStoreDefinition;
+        /**
+         * Browse and install extensions from the official OrgNote extension registry.
+         */
         useExtensionRegistry: ExtensionRegistryStoreDefinition;
+        /**
+         * Guard files with validation rules before allowing operations.
+         * Prevents accidental overwrites and enforces naming conventions.
+         */
         useFileGuard: FileGuardStoreDefinition;
         useAuth: AuthStoreDefinition;
+        /**
+         * Bidirectional note synchronization between local storage and remote server.
+         * Creates a sync plan (diff), then executes upload/download/delete operations.
+         */
         useSync: SyncStoreDefinition;
+        /**
+         * Org-mode editor state: registered widgets, [CodeMirror](https://codemirror.net/) extensions,
+         * active editor context (selection, cursor position).
+         *
+         * @example
+         * ```typescript
+         * const editor = api.core.useEditor();
+         * editor.addWidgets({
+         *   type: WidgetType.Inline,
+         *   nodeType: 'link',
+         *   id: 'my-link-widget',
+         *   decorationType: 'replace',
+         *   widgetBuilder: (params) => { ... },
+         * });
+         * ```
+         */
         useEditor: EditorStoreDefinition;
+        /**
+         * Babel-style code transformation store.
+         * Used for transpiling extension source code at runtime.
+         */
         useBabel: BabelStoreDefinition;
         useFileSearch: FileSearchStoreDefinition;
         useFileMeta: FileMetaStoreDefinition;
@@ -79,8 +279,36 @@ export interface OrgNoteApi {
         useFileContent: UseFileContent;
         app: App;
     };
+    /**
+     * Utility functions available to extensions.
+     *
+     * Includes platform detection, CSS manipulation, clipboard access,
+     * file upload dialogs, logging, TOML parsing, and URL building.
+     */
     utils: {
+        /**
+         * Detect the current platform (mobile, desktop, electron, browser, OS).
+         *
+         * @example
+         * ```typescript
+         * if (api.utils.platform.is.mobile) {
+         *   // mobile-specific logic
+         * }
+         * ```
+         */
         platform: PlatformDetection;
+        /**
+         * Execute platform-specific code branches with a single call.
+         *
+         * @example
+         * ```typescript
+         * const result = await api.utils.platformMatch({
+         *   mobile: () => 'compact layout',
+         *   desktop: () => 'full layout',
+         *   default: () => 'fallback layout',
+         * });
+         * ```
+         */
         platformMatch: PlatformMatch;
         clientOnly: PlatformSpecificFn;
         mobileOnly: PlatformSpecificFn;
@@ -92,18 +320,56 @@ export interface OrgNoteApi {
         getNumericCssVar: GetNumericCssVar;
         getCssProperty: GetCssProperty;
         getCssNumericProperty: GetCssNumericProperty;
+        /**
+         * Apply CSS custom properties to the document root.
+         * Commonly used by theme extensions to override colors.
+         *
+         * @example
+         * ```typescript
+         * api.utils.applyCSSVariables({
+         *   '--primary': '#ff6600',
+         *   '--bg': '#1a1a2e',
+         * });
+         * ```
+         */
         applyCSSVariables: ApplyCSSVariables<string>;
         resetCSSVariables: ResetCSSVariables<string>;
+        /**
+         * Inject a scoped `<style>` block identified by a unique scope name.
+         * Calling again with the same scope name replaces the previous styles.
+         */
         applyScopedStyles: ApplyScopedStyles;
         removeScopedStyles: RemoveScopedStyles;
         copyToClipboard: (text: string) => Promise<void>;
         uploadFiles: (params: MultipleUploadParams) => Promise<FileList>;
         uploadFile: (params?: UploadParams) => Promise<File | undefined>;
+        /**
+         * Structured logger scoped to the extension.
+         * Messages are persisted and visible in the OrgNote log viewer.
+         */
         logger: Logger;
+        /**
+         * Parse a [TOML](https://toml.io/) string into a JavaScript object.
+         * Used for reading `.toml` configuration files.
+         */
         parseToml: typeof parseToml;
         stringifyToml: typeof stringifyToml;
+        /**
+         * Build an OrgNote deep-link URL (for native app or web).
+         *
+         * @example
+         * ```typescript
+         * const url = api.utils.buildOrgNoteUrl('/notes/abc123', {
+         *   target: 'native-app',
+         * });
+         * ```
+         */
         buildOrgNoteUrl: BuildOrgNoteUrl;
     };
+    /**
+     * UI-related stores for controlling visual elements: modals, sidebars,
+     * themes, fonts, context menus, and screen/keyboard state.
+     */
     ui: {
         useFonts: FontStoreDefinition;
         useSplashScreen: UseSplashScreen;
@@ -111,15 +377,55 @@ export interface OrgNoteApi {
         useSidebar: SidebarStoreDefinition;
         useRightSidebar: RightSidebarStoreDefinition;
         usePinnedCommands: PinnedCommandsStoreDefinition;
+        /**
+         * Open modal dialogs with custom Vue components.
+         *
+         * @example
+         * ```typescript
+         * const modal = api.ui.useModal();
+         * const result = await modal.open(MyDialogComponent, {
+         *   title: 'Confirm action',
+         * });
+         * ```
+         */
         useModal: ModalStoreDefinition;
         useSettingsUi: SettingsUiStoreDefinition;
+        /**
+         * Show a confirmation dialog and await the user's response.
+         *
+         * @example
+         * ```typescript
+         * const { confirm } = api.ui.useConfirmationModal();
+         * const confirmed = await confirm({
+         *   title: 'Delete note?',
+         *   message: 'This action cannot be undone.',
+         * });
+         * if (confirmed) { ... }
+         * ```
+         */
         useConfirmationModal: UseConfirmationModal;
         useScreenDetection: UseScreenDetection;
         useKeyboardState: UseKeyboardState;
         useContextMenu: ContextMenuStoreDefinition;
+        /**
+         * Manage the active color theme.
+         * Theme extensions use this store to register and activate their themes.
+         */
         useTheme: ThemeStoreDefinition;
     };
+    /**
+     * Direct access to the Vue ecosystem.
+     */
     vue: {
+        /**
+         * The [Vue Router](https://router.vuejs.org/) instance.
+         * Use for programmatic navigation within the OrgNote application.
+         *
+         * @example
+         * ```typescript
+         * api.vue.router.push({ name: 'note', params: { id: 'abc123' } });
+         * ```
+         */
         router: Router;
     };
 }

package/constants/file-sort-defaults.d.ts

@@ -0,0 +1,2 @@
+import { FileSortConfig } from '../models/file-sort.js';
+export declare const DEFAULT_FILE_SORT_CONFIG: FileSortConfig;

package/constants/file-sort-defaults.js

@@ -0,0 +1,5 @@
+export const DEFAULT_FILE_SORT_CONFIG = {
+    field: 'name',
+    direction: 'asc',
+    directoriesFirst: true,
+};

package/constants/i18n-keys.d.ts

@@ -76,6 +76,12 @@ export declare enum i18n {
     DELETE = "delete",
     RENAME = "rename",
     COPY = "copy",
+    MOVE = "move",
+    SORT_BY_NAME = "sort by name",
+    SORT_BY_MODIFIED = "sort by modified",
+    SORT_BY_SIZE = "sort by size",
+    SORT_ASCENDING = "ascending",
+    SORT_DESCENDING = "descending",
     CREATE_FILE = "create file",
     FILE_NAME = "file name",
     DIR_NAME = "directory name",
@@ -236,6 +242,14 @@ export declare const I18N: {
     CREATE_FILE: DefaultCommands.CREATE_FILE;
     RENAME_FILE: DefaultCommands.RENAME_FILE;
     DELETE_FILE: DefaultCommands.DELETE_FILE;
+    COPY_FILE: DefaultCommands.COPY_FILE;
+    MOVE_FILE: DefaultCommands.MOVE_FILE;
+    SELECT_FILE: DefaultCommands.SELECT_FILE;
+    SELECT_ALL_FILES: DefaultCommands.SELECT_ALL_FILES;
+    DESELECT_ALL_FILES: DefaultCommands.DESELECT_ALL_FILES;
+    EXECUTE_PENDING_FILE_OPERATION: DefaultCommands.EXECUTE_PENDING_FILE_OPERATION;
+    CANCEL_PENDING_FILE_OPERATION: DefaultCommands.CANCEL_PENDING_FILE_OPERATION;
+    SORT_FILES: DefaultCommands.SORT_FILES;
     CONFIRM_FILE_DELETION: DefaultCommands.CONFIRM_FILE_DELETION;
     NEW_FILE_PATH: DefaultCommands.NEW_FILE_PATH;
     SHOW_MOBILE_FILE_SEARCH: DefaultCommands.SHOW_MOBILE_FILE_SEARCH;
@@ -357,6 +371,12 @@ export declare const I18N: {
     DELETE: i18n.DELETE;
     RENAME: i18n.RENAME;
     COPY: i18n.COPY;
+    MOVE: i18n.MOVE;
+    SORT_BY_NAME: i18n.SORT_BY_NAME;
+    SORT_BY_MODIFIED: i18n.SORT_BY_MODIFIED;
+    SORT_BY_SIZE: i18n.SORT_BY_SIZE;
+    SORT_ASCENDING: i18n.SORT_ASCENDING;
+    SORT_DESCENDING: i18n.SORT_DESCENDING;
     FILE_NAME: i18n.FILE_NAME;
     DIR_NAME: i18n.DIR_NAME;
     FINISH_SETUP: i18n.FINISH_SETUP;

package/constants/i18n-keys.js

@@ -77,6 +77,12 @@ export var i18n;
     i18n["DELETE"] = "delete";
     i18n["RENAME"] = "rename";
     i18n["COPY"] = "copy";
+    i18n["MOVE"] = "move";
+    i18n["SORT_BY_NAME"] = "sort by name";
+    i18n["SORT_BY_MODIFIED"] = "sort by modified";
+    i18n["SORT_BY_SIZE"] = "sort by size";
+    i18n["SORT_ASCENDING"] = "ascending";
+    i18n["SORT_DESCENDING"] = "descending";
     i18n["CREATE_FILE"] = "create file";
     i18n["FILE_NAME"] = "file name";
     i18n["DIR_NAME"] = "directory name";

package/constants/index.d.ts

@@ -7,3 +7,4 @@ export * from './git-errors.js';
 export * from './extension-errors.js';
 export * from './file-guard-errors.js';
 export * from './oauth-providers.js';
+export * from './file-sort-defaults.js';

package/constants/index.js

@@ -7,3 +7,4 @@ export * from "./git-errors.js";
 export * from "./extension-errors.js";
 export * from "./file-guard-errors.js";
 export * from "./oauth-providers.js";
+export * from "./file-sort-defaults.js";

package/models/default-commands.d.ts

@@ -67,6 +67,14 @@ export declare enum DefaultCommands {
     CREATE_FILE = "create file",
     RENAME_FILE = "rename file",
     DELETE_FILE = "delete file",
+    COPY_FILE = "copy file",
+    MOVE_FILE = "move file",
+    SELECT_FILE = "select file",
+    SELECT_ALL_FILES = "select all files",
+    DESELECT_ALL_FILES = "deselect all files",
+    EXECUTE_PENDING_FILE_OPERATION = "paste files here",
+    CANCEL_PENDING_FILE_OPERATION = "cancel file operation",
+    SORT_FILES = "sort files",
     CONFIRM_FILE_DELETION = "are you sure you want to delete file?",
     NEW_FILE_PATH = "new file path",
     SHOW_MOBILE_FILE_SEARCH = "show mobile file search",

package/models/default-commands.js

@@ -82,6 +82,14 @@ export var DefaultCommands;
     DefaultCommands["CREATE_FILE"] = "create file";
     DefaultCommands["RENAME_FILE"] = "rename file";
     DefaultCommands["DELETE_FILE"] = "delete file";
+    DefaultCommands["COPY_FILE"] = "copy file";
+    DefaultCommands["MOVE_FILE"] = "move file";
+    DefaultCommands["SELECT_FILE"] = "select file";
+    DefaultCommands["SELECT_ALL_FILES"] = "select all files";
+    DefaultCommands["DESELECT_ALL_FILES"] = "deselect all files";
+    DefaultCommands["EXECUTE_PENDING_FILE_OPERATION"] = "paste files here";
+    DefaultCommands["CANCEL_PENDING_FILE_OPERATION"] = "cancel file operation";
+    DefaultCommands["SORT_FILES"] = "sort files";
     DefaultCommands["CONFIRM_FILE_DELETION"] = "are you sure you want to delete file?";
     DefaultCommands["NEW_FILE_PATH"] = "new file path";
     DefaultCommands["SHOW_MOBILE_FILE_SEARCH"] = "show mobile file search";

package/models/file-manager-store.d.ts

@@ -1,13 +1,35 @@
 import { StoreDefinition } from './store.js';
-import { Ref, ShallowRef } from 'vue';
+import { ComputedRef, Ref, ShallowRef } from 'vue';
 import { DiskFile } from './file-system.js';
+import { FileSortConfig } from './file-sort.js';
+export type PendingFileOperation = {
+    type: 'copy' | 'move';
+    paths: string[];
+};
 export interface FileManagerStore {
     path: Ref<string>;
     focusFile: ShallowRef<DiskFile | undefined>;
     focusDirPath: Ref<string>;
     searchQuery: Ref<string>;
     mobileFileSearchActive: Ref<boolean>;
-    deleteFile: (path?: string) => Promise<void>;
+    files: Ref<DiskFile[]>;
+    sortConfig: Ref<FileSortConfig>;
+    sortedFiles: ComputedRef<DiskFile[]>;
+    loadFiles: () => Promise<void>;
+    selectionMode: ComputedRef<boolean>;
+    selectedFiles: Ref<Set<string>>;
+    operationTargets: ComputedRef<string[]>;
+    pendingOperation: Ref<PendingFileOperation | undefined>;
+    toggleSelection: (path: string) => void;
+    selectFiles: (files: DiskFile[]) => void;
+    clearSelection: () => void;
+    startCopy: (paths: string[]) => void;
+    startMove: (paths: string[]) => void;
+    executePending: (dest: string) => Promise<void>;
+    cancelPending: () => void;
+    copyFiles: (paths: string[], dest: string) => Promise<void>;
+    moveFiles: (paths: string[], dest: string) => Promise<void>;
+    deleteFiles: (paths: string[]) => Promise<void>;
     createFolder: (path?: string) => Promise<void>;
     createFile: (path?: string) => Promise<void>;
 }

package/models/file-sort.d.ts

@@ -0,0 +1,8 @@
+import { SortDirection } from './sort-direction.js';
+import { DiskFile } from './file-system.js';
+export type FileSortField = keyof Pick<DiskFile, 'name' | 'mtime' | 'size'>;
+export interface FileSortConfig {
+    readonly field: FileSortField;
+    readonly direction: SortDirection;
+    readonly directoriesFirst: boolean;
+}

package/models/file-sort.js

@@ -0,0 +1 @@
+export {};

package/models/file-system-store.d.ts

@@ -13,6 +13,7 @@ export interface FileSystemStore {
     rmdir(path: string | string[]): Promise<void>;
     fileInfo(path: string | string[]): Promise<DiskFile | undefined>;
     readDir(path?: string | string[]): Promise<DiskFile[]>;
+    copyFile(src: string | string[], dest: string | string[]): Promise<void>;
     dropFileSystem: () => Promise<void>;
     prettyVault: Ref<string>;
 }

package/models/index.d.ts

@@ -49,6 +49,8 @@ export * from './sync-store.js';
 export * from './files-store.js';
 export * from './buffer-viewer-store.js';
 export * from './file-manager-store.js';
+export * from './sort-direction.js';
+export * from './file-sort.js';
 export * from './auth-store.js';
 export * from './commands-store.js';
 export * from './commands-group-store.js';

package/models/index.js

@@ -51,6 +51,8 @@ export * from "./sync-store.js";
 export * from "./files-store.js";
 export * from "./buffer-viewer-store.js";
 export * from "./file-manager-store.js";
+export * from "./sort-direction.js";
+export * from "./file-sort.js";
 export * from "./auth-store.js";
 export * from "./commands-store.js";
 export * from "./commands-group-store.js";

package/models/sort-direction.d.ts

@@ -0,0 +1 @@
+export type SortDirection = 'asc' | 'desc';

package/models/sort-direction.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "orgnote-api",
-  "version": "0.41.15",
+  "version": "0.41.17",
   "description": "Official API for creating extensions for OrgNote app",
   "type": "module",
   "main": "./index.js",
   "packageManager": "bun@1.1.22",
   "scripts": {
     "test": "vitest",
+    "test:ci": "vitest run",
     "build": "npm run clear && tspc --project tsconfig.json",
     "clear": "rm -rf dist",
     "lint": "eslint -c ./eslint.config.js \"./src*/**/*.{ts,js,cjs,mjs}\"",
@@ -17,7 +18,10 @@
     "fix-esm-imports": "fix-esm-import-path ./dist",
     "prepub": "bun run build && bun run fix-esm-imports && cp -rf package.json package-lock.json README.md dist/",
     "pub": "bun run prepub && cd dist && npm publish",
-    "pub:yalc": "bun run prepub && cd dist && yalc publish --push"
+    "pub:yalc": "bun run prepub && cd dist && yalc publish --push",
+    "docs:dev": "cd docs && bun run dev",
+    "docs:build": "cd docs && bun run build",
+    "docs:preview": "cd docs && bun run preview"
   },
   "repository": {
     "type": "git",
@@ -53,6 +57,7 @@
   "devDependencies": {
     "@eslint/js": "9.25.1",
     "@openapitools/openapi-generator-cli": "2.19.1",
+    "@rollup/rollup-linux-arm64-gnu": "4.14.2",
     "@types/node": "22.14.1",
     "eslint": "9.25.1",
     "eslint-plugin-sonarjs": "3.0.5",

package/utils/index.d.ts

@@ -12,3 +12,4 @@ export * from './to-error.js';
 export * from './auth-state.js';
 export * from './nullable-guards.js';
 export * from './binary.js';
+export * from './sort-files.js';

package/utils/index.js

@@ -12,3 +12,4 @@ export * from "./to-error.js";
 export * from "./auth-state.js";
 export * from "./nullable-guards.js";
 export * from "./binary.js";
+export * from "./sort-files.js";

package/utils/sort-files.d.ts

@@ -0,0 +1,3 @@
+import { DiskFile } from '../models/file-system.js';
+import { FileSortConfig } from '../models/file-sort.js';
+export declare const sortFiles: (files: readonly DiskFile[], config: FileSortConfig) => DiskFile[];

package/utils/sort-files.js

@@ -0,0 +1,26 @@
+const DIRECTORY_TYPE = 'directory';
+const fieldAccessors = {
+    name: (f) => f.name.toLowerCase(),
+    mtime: (f) => f.mtime,
+    size: (f) => f.size,
+};
+const compareValues = (a, b) => {
+    if (typeof a === 'string' && typeof b === 'string')
+        return a.localeCompare(b);
+    return a - b;
+};
+const compareByField = (a, b, config) => {
+    const accessor = fieldAccessors[config.field];
+    const result = compareValues(accessor(a), accessor(b));
+    return config.direction === 'asc' ? result : -result;
+};
+const compareWithDirectoriesFirst = (a, b, config) => {
+    if (!config.directoriesFirst)
+        return compareByField(a, b, config);
+    const aIsDir = a.type === DIRECTORY_TYPE;
+    const bIsDir = b.type === DIRECTORY_TYPE;
+    if (aIsDir !== bIsDir)
+        return aIsDir ? -1 : 1;
+    return compareByField(a, b, config);
+};
+export const sortFiles = (files, config) => [...files].sort((a, b) => compareWithDirectoriesFirst(a, b, config));

package/utils/sort-files.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/utils/sort-files.spec.js

@@ -0,0 +1,84 @@
+import { test, expect } from 'vitest';
+import { sortFiles } from "./sort-files.js";
+import { DEFAULT_FILE_SORT_CONFIG } from "../constants/file-sort-defaults.js";
+const createFile = (overrides) => ({
+    name: 'file.org',
+    path: '/file.org',
+    type: 'file',
+    size: 100,
+    mtime: 1000,
+    ...overrides,
+});
+const DIR_ALPHA = createFile({ name: 'alpha', path: '/alpha', type: 'directory', size: 0, mtime: 3000 });
+const DIR_BETA = createFile({ name: 'beta', path: '/beta', type: 'directory', size: 0, mtime: 1000 });
+const FILE_A = createFile({ name: 'a.org', path: '/a.org', size: 200, mtime: 2000 });
+const FILE_B = createFile({ name: 'b.org', path: '/b.org', size: 50, mtime: 5000 });
+const FILE_C = createFile({ name: 'c.org', path: '/c.org', size: 300, mtime: 1000 });
+test('sortFiles returns empty array for empty input', () => {
+    expect(sortFiles([], DEFAULT_FILE_SORT_CONFIG)).toEqual([]);
+});
+test('sortFiles does not mutate original array', () => {
+    const original = [FILE_B, FILE_A];
+    const sorted = sortFiles(original, DEFAULT_FILE_SORT_CONFIG);
+    expect(sorted).not.toBe(original);
+    expect(original[0]).toBe(FILE_B);
+});
+test('sortFiles sorts by name ascending with directories first by default', () => {
+    const files = [FILE_B, DIR_BETA, FILE_A, DIR_ALPHA];
+    const sorted = sortFiles(files, DEFAULT_FILE_SORT_CONFIG);
+    expect(sorted.map((f) => f.name)).toEqual(['alpha', 'beta', 'a.org', 'b.org']);
+});
+test('sortFiles sorts by name descending with directories first', () => {
+    const config = { field: 'name', direction: 'desc', directoriesFirst: true };
+    const files = [FILE_A, DIR_ALPHA, FILE_B, DIR_BETA];
+    const sorted = sortFiles(files, config);
+    expect(sorted.map((f) => f.name)).toEqual(['beta', 'alpha', 'b.org', 'a.org']);
+});
+test('sortFiles sorts by name ascending without directories first', () => {
+    const config = { field: 'name', direction: 'asc', directoriesFirst: false };
+    const files = [FILE_B, DIR_BETA, FILE_A, DIR_ALPHA];
+    const sorted = sortFiles(files, config);
+    expect(sorted.map((f) => f.name)).toEqual(['a.org', 'alpha', 'b.org', 'beta']);
+});
+test('sortFiles sorts by mtime ascending', () => {
+    const config = { field: 'mtime', direction: 'asc', directoriesFirst: false };
+    const files = [FILE_B, FILE_A, FILE_C];
+    const sorted = sortFiles(files, config);
+    expect(sorted.map((f) => f.name)).toEqual(['c.org', 'a.org', 'b.org']);
+});
+test('sortFiles sorts by mtime descending with directories first', () => {
+    const config = { field: 'mtime', direction: 'desc', directoriesFirst: true };
+    const files = [FILE_A, DIR_BETA, FILE_B, DIR_ALPHA];
+    const sorted = sortFiles(files, config);
+    expect(sorted.map((f) => f.name)).toEqual(['alpha', 'beta', 'b.org', 'a.org']);
+});
+test('sortFiles sorts by size ascending', () => {
+    const config = { field: 'size', direction: 'asc', directoriesFirst: false };
+    const files = [FILE_C, FILE_A, FILE_B];
+    const sorted = sortFiles(files, config);
+    expect(sorted.map((f) => f.name)).toEqual(['b.org', 'a.org', 'c.org']);
+});
+test('sortFiles sorts by size descending', () => {
+    const config = { field: 'size', direction: 'desc', directoriesFirst: false };
+    const files = [FILE_A, FILE_C, FILE_B];
+    const sorted = sortFiles(files, config);
+    expect(sorted.map((f) => f.name)).toEqual(['c.org', 'a.org', 'b.org']);
+});
+test('sortFiles handles single file', () => {
+    const sorted = sortFiles([FILE_A], DEFAULT_FILE_SORT_CONFIG);
+    expect(sorted).toEqual([FILE_A]);
+});
+test('sortFiles handles all directories', () => {
+    const sorted = sortFiles([DIR_BETA, DIR_ALPHA], DEFAULT_FILE_SORT_CONFIG);
+    expect(sorted.map((f) => f.name)).toEqual(['alpha', 'beta']);
+});
+test('sortFiles handles all files (no directories)', () => {
+    const sorted = sortFiles([FILE_C, FILE_A, FILE_B], DEFAULT_FILE_SORT_CONFIG);
+    expect(sorted.map((f) => f.name)).toEqual(['a.org', 'b.org', 'c.org']);
+});
+test('sortFiles name comparison is case-insensitive', () => {
+    const upper = createFile({ name: 'Zebra.org', path: '/Zebra.org' });
+    const lower = createFile({ name: 'apple.org', path: '/apple.org' });
+    const sorted = sortFiles([upper, lower], DEFAULT_FILE_SORT_CONFIG);
+    expect(sorted.map((f) => f.name)).toEqual(['apple.org', 'Zebra.org']);
+});