@deckbuilderkit/view-explorer 0.0.0-stage → 0.1.0

package/src/server.ts

@@ -0,0 +1,156 @@
+import { statSync } from 'node:fs';
+import { openWithDefault, revealInFolder } from '@deckbuilderkit/platform';
+import { defineServerView, invalid, isRecord, type ServerViewDef } from '@deckbuilderkit/server-core';
+import { dialogRoutes, editorRoutes, fromPlatform, pickedPaths, recordRoutes, rootedFs, type RootedFs } from '@deckbuilderkit/server-mods';
+import type { ExplorerSettings } from './explorer-state';
+
+/** The part of the server settings the Explorer view owns; the app's `Settings` extends it. */
+export interface ExplorerServerSettings {
+  /** Explorer screen state; checked by `validExplorer`. */
+  explorer?: ExplorerSettings;
+}
+
+const MARKDOWN_MODES: unknown[] = ['live', 'edit', 'split', 'preview'];
+const MAX_TABS_LAYOUT_BYTES = 64 * 1024;
+const MAX_EXPANDED_IDS = 2000;
+const MAX_ID_LENGTH = 64;
+const ID = /^[\w-]{1,64}$/;
+
+const isStringArray = (v: unknown): v is string[] => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+const validPair = (v: unknown): [number, number] | null =>
+  Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number' && n >= 0 && n <= 1) && Math.abs(v[0] + v[1] - 1) <= 0.01
+    ? [v[0], v[1]]
+    : null;
+
+/** A project-id to connection-id map, or null when malformed. */
+function validConnections(raw: unknown): Record<string, string> | null {
+  if (!isRecord(raw)) return null;
+  const out: Record<string, string> = {};
+  for (const [project, id] of Object.entries(raw)) {
+    if (!ID.test(project) || typeof id !== 'string' || !ID.test(id)) return null;
+    out[project] = id;
+  }
+  return out;
+}
+
+/** A copy of `raw` when it is a well-formed explorer state within the size limits, else null. */
+export function validExplorer(raw: unknown): ExplorerSettings | null {
+  const r = raw as Partial<ExplorerSettings> | null;
+  if (typeof r !== 'object' || r === null) return null;
+  const { sizes, collapsed, expanded, tabs, trees, treeSizes, markdownMode, wrapLines, sqlSizes, connections } = r;
+  if (!Array.isArray(sizes) || sizes.length !== 2 || !sizes.every((n) => typeof n === 'number' && n >= 0 && n <= 1)) return null;
+  if (Math.abs(sizes[0] + sizes[1] - 1) > 0.01) return null;
+  if (typeof collapsed !== 'boolean' || typeof expanded !== 'object' || expanded === null || Array.isArray(expanded)) return null;
+  const out: Record<string, string[]> = {};
+  for (const [project, ids] of Object.entries(expanded)) {
+    if (project.length > MAX_ID_LENGTH || !isStringArray(ids) || ids.length > MAX_EXPANDED_IDS) return null;
+    out[project] = ids;
+  }
+  if (tabs !== undefined && (typeof tabs !== 'object' || tabs === null || JSON.stringify(tabs).length >= MAX_TABS_LAYOUT_BYTES)) return null;
+  if (trees !== undefined && (!isStringArray(trees) || trees.length < 1 || trees.length > 2 || trees.some((id) => id.length > MAX_ID_LENGTH))) return null;
+  const pair = treeSizes === undefined ? undefined : validPair(treeSizes);
+  if (treeSizes !== undefined && !pair) return null;
+  if (markdownMode !== undefined && !MARKDOWN_MODES.includes(markdownMode)) return null;
+  if (wrapLines !== undefined && typeof wrapLines !== 'boolean') return null;
+  const sqlPair = sqlSizes === undefined ? undefined : validPair(sqlSizes);
+  if (sqlSizes !== undefined && !sqlPair) return null;
+  const conns = connections === undefined ? undefined : validConnections(connections);
+  if (connections !== undefined && !conns) return null;
+  return {
+    sizes: [sizes[0], sizes[1]],
+    collapsed,
+    expanded: out,
+    ...(trees !== undefined && { trees }),
+    ...(pair && { treeSizes: pair }),
+    ...(markdownMode !== undefined && { markdownMode }),
+    ...(wrapLines !== undefined && { wrapLines }),
+    ...(sqlPair && { sqlSizes: sqlPair }),
+    ...(conns && { connections: conns }),
+    ...(tabs !== undefined && { tabs }),
+  };
+}
+
+type Stores = {
+  projects: Parameters<typeof recordRoutes>[0];
+  projectRoots: Parameters<typeof rootedFs>[0]['roots'];
+  pickedFolders: ReturnType<typeof pickedPaths>;
+};
+
+const isDirectory = (path: string) => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+export interface ExplorerServerOptions {
+  /** False: the delete route takes one path only. */
+  multiDelete?: boolean;
+}
+
+export type ExplorerServerView = ServerViewDef<ExplorerServerSettings> & {
+  /** A project folder as a terminal's working directory; valid once the view is mounted. */
+  resolveCwd(root: string, path: string): Promise<string>;
+};
+
+/**
+ * Server half of the Explorer view: the rooted file system routes, upload/download tickets, the
+ * project record routes, reveal/open, the editors and folder dialog routes, and the `explorer`
+ * settings group. Needs `ctx.stores.projects`, `projectRoots` and `pickedFolders`.
+ */
+export function explorerServerView(opts: ExplorerServerOptions = {}): ExplorerServerView {
+  let fs: RootedFs | undefined;
+  const mounted = () => {
+    if (!fs) throw new Error('The Explorer view is not mounted.');
+    return fs;
+  };
+  const view = defineServerView<ExplorerServerSettings>({
+    id: 'explorer',
+    routes(ctx) {
+      const stores = ctx.stores as unknown as Stores;
+      const rooted = rootedFs({ multiDelete: opts.multiDelete, roots: stores.projectRoots });
+      fs = rooted;
+      const target = async (json: <T>() => Promise<T>) => {
+        const { root, path } = await json<{ root?: unknown; path?: unknown }>();
+        return (await rooted.resolve(String(root), typeof path === 'string' ? path : '', { mustExist: true })).real;
+      };
+      void migrateConnections(ctx.settings);
+      return {
+        ...recordRoutes(stores.projects, '/api/projects'),
+        ...rooted.routes,
+        ...dialogRoutes({ picked: stores.pickedFolders }),
+        ...editorRoutes({ dir: ctx.dataDir, fs: rooted }),
+        'POST /api/fs/reveal': async ({ json }) => {
+          await revealInFolder(await target(json)).catch(fromPlatform);
+          return { ok: true };
+        },
+        'POST /api/fs/open': async ({ json }) => {
+          await openWithDefault(await target(json)).catch(fromPlatform);
+          return { ok: true };
+        },
+      };
+    },
+    unauthenticated: () => mounted().openRoutes,
+    settings: { validate: { explorer: validExplorer } },
+  });
+  return {
+    ...view,
+    async resolveCwd(root, path) {
+      const { real } = await mounted().resolve(root, path, { mustExist: true });
+      if (!isDirectory(real)) throw invalid('notADirectory', 'The path is not a folder.');
+      return real;
+    },
+  };
+}
+
+/** Carries the Workbench's old `explorerConnections` into `explorer.connections` when the latter is unset. */
+async function migrateConnections(settings: { load(): Promise<ExplorerServerSettings & { workbench?: { explorerConnections?: unknown } }>; save?(patch: Record<string, unknown>): Promise<unknown> }): Promise<void> {
+  if (!settings.save) return;
+  const s = await settings.load();
+  const old = s.workbench?.explorerConnections;
+  if (!s.explorer || s.explorer.connections !== undefined || !old) return;
+  const connections = validConnections(old);
+  if (connections) await settings.save({ explorer: { ...s.explorer, connections } });
+}

package/src/settings/cards.tsx

@@ -0,0 +1,99 @@
+import { useState } from 'react';
+import { deepEqual, FILE_DEFAULTS, fileSettingsOf, SettingItem, type SettingsCardProps, type SettingsFieldProps, useResync } from '@deckbuilderkit/ui';
+import { t } from '../i18n';
+import type { ExplorerViewSettings } from '../settings';
+
+function NestingField({ value, onChange }: { value: Record<string, string>; onChange: (next: Record<string, string>) => void }) {
+  const toText = (v: Record<string, string>) => Object.entries(v).map(([k, c]) => `${k}: ${c}`).join(String.fromCharCode(10));
+  const [text, setText] = useState(toText(value));
+  const area = useResync(value, () => setText(toText(value)));
+  return (
+    <SettingItem id="files.nestingPatterns" modified={!deepEqual(value, FILE_DEFAULTS.nestingPatterns)}>
+      <div className="field">
+        <span className="mono-label">{t('settings.explorer.nesting.patterns')}</span>
+        <textarea
+          ref={area}
+          value={text}
+          rows={6}
+          spellCheck={false}
+          aria-label={t('settings.explorer.nesting.patterns')}
+          onChange={(e) => setText(e.target.value)}
+          onBlur={() => {
+            const next: Record<string, string> = {};
+            for (const line of text.split(String.fromCharCode(10))) {
+              const at = line.indexOf(':');
+              const parent = line.slice(0, at).trim();
+              const children = line.slice(at + 1).trim();
+              if (at > 0 && parent && children) next[parent] = children;
+            }
+            onChange(next);
+          }}
+        />
+        <span className="muted">{t('settings.explorer.nesting.patterns.hint')}</span>
+      </div>
+    </SettingItem>
+  );
+}
+
+function ExcludeField({ value, onChange }: { value: string[]; onChange: (next: string[]) => void }) {
+  const [text, setText] = useState(value.join('\n'));
+  const area = useResync(value, () => setText(value.join('\n')));
+  return (
+    <SettingItem id="files.exclude" modified={!deepEqual(value, FILE_DEFAULTS.exclude)}>
+      <div className="field">
+        <span className="mono-label">{t('settings.explorer.exclude')}</span>
+        <textarea
+          ref={area}
+          value={text}
+          rows={4}
+          spellCheck={false}
+          aria-label={t('settings.explorer.exclude')}
+          onChange={(e) => setText(e.target.value)}
+          onBlur={() => onChange(text.split('\n').map((l) => l.trim()).filter(Boolean))}
+        />
+        <span className="muted">{t('settings.explorer.exclude.hint')}</span>
+      </div>
+    </SettingItem>
+  );
+}
+
+/** The hand-written rows of the `files.nestingPatterns` and `files.exclude` settings (search results show them too). */
+export function NestingSettingField({ settings, onChange }: SettingsFieldProps<ExplorerViewSettings>) {
+  const files = fileSettingsOf(settings.files);
+  return <NestingField value={files.nestingPatterns} onChange={(nestingPatterns) => onChange({ files: { ...files, nestingPatterns } })} />;
+}
+
+export function ExcludeSettingField({ settings, onChange }: SettingsFieldProps<ExplorerViewSettings>) {
+  const files = fileSettingsOf(settings.files);
+  return <ExcludeField value={files.exclude} onChange={(exclude) => onChange({ files: { ...files, exclude } })} />;
+}
+
+/** How the Explorer tree and its tabs behave (`files.*` settings, shared with the file tabs). */
+export function ExplorerCard({ settings, onChange, row }: SettingsCardProps<ExplorerViewSettings>) {
+  const files = fileSettingsOf(settings.files);
+  const set = (patch: Partial<typeof files>) => onChange({ files: { ...files, ...patch } });
+  return (
+    <>
+      <section className="section">
+        <h4 className="mono-label">{t('settings.explorer.tabs')}</h4>
+        <div className="card form">
+          {['previewTabs', 'autoReveal', 'breadcrumbs', 'restoreTabs', 'markdownToc'].map((k) => row(`files.${k}`))}
+        </div>
+      </section>
+      <section className="section">
+        <h4 className="mono-label">{t('settings.explorer.view')}</h4>
+        <div className="card form">
+          {row('files.compactFolders')}
+          {row('files.sortOrder')}
+          {row('files.fileNesting')}
+          {row('git.explorerDecorations')}
+          {row('files.showHidden')}
+          {row('files.confirmDelete')}
+          {row('files.confirmDragDrop')}
+          {files.fileNesting && <NestingField value={files.nestingPatterns} onChange={(nestingPatterns) => set({ nestingPatterns })} />}
+          <ExcludeField value={files.exclude} onChange={(exclude) => set({ exclude })} />
+        </div>
+      </section>
+    </>
+  );
+}

package/src/settings.ts

@@ -0,0 +1,107 @@
+import { DEFAULT_FORMAT_OPTIONS, type SqlFormatOptions } from '@deckbuilderkit/editor/options';
+import type { CopyFormat, SqlRunnerSettings } from '@deckbuilderkit/sql-ui';
+import { DEFAULT_RESULT_FORMAT, FILE_DEFAULTS, fileBoolSetting, fileEnumSetting, fileSettingsOf, type FileSettings, type GitSettings, type LogSettings, type ResultFormat, type SectionPath, type SettingDef, SORT_ORDERS } from '@deckbuilderkit/ui';
+
+import type { ExplorerSettings } from './explorer-state';
+
+export type { ExplorerSettings };
+
+/** The part of the Workbench state the Explorer reads (SQL files) and writes (`doc`, to open a file there). */
+export interface ExplorerWorkbench {
+  /** Project ids allowed to run SQL from the Explorer. */
+  explorerProjects: string[];
+  maxRows: number;
+  results: Partial<ResultFormat>;
+  copyFormat: CopyFormat;
+  confirmDestructive: boolean;
+  queryTimeout: number;
+  format: Partial<SqlFormatOptions>;
+  doc: { kind: 'default' } | { kind: 'file'; project: string; path: string };
+}
+
+/** The part of the app settings the Explorer reads and writes; the app's `Settings` extends it. */
+export interface ExplorerViewSettings {
+  /** State of the Explorer screen; the server validates it. */
+  explorer?: ExplorerSettings;
+  /** Log viewer: highlight words and bookmarks (keyed `<projectId>:<path>`). */
+  logs?: LogSettings;
+  /** How text files are saved and how the Explorer shows files. */
+  files?: FileSettings;
+  /** Read only: the editor's word wrap. */
+  editor?: { wordWrap?: boolean };
+  /** Read only: closing dirty tabs. */
+  general?: { confirmCloseDirty?: boolean };
+  /** Read only: the sidebar side of the app's window settings. */
+  window?: { sidebarSide?: 'left' | 'right' };
+  /** Read only: the REST view's active environment, whose variables `.curl` files use. */
+  rest?: { environment?: string };
+  /** Read only: the shared git group. */
+  git?: GitSettings;
+  /** The Workbench state, for SQL files. */
+  workbench?: Partial<ExplorerWorkbench>;
+}
+
+export const editorSettingsOf = (s: ExplorerViewSettings) => ({ wordWrap: s.editor?.wordWrap ?? true });
+export const generalSettingsOf = (s: ExplorerViewSettings) => ({ confirmCloseDirty: s.general?.confirmCloseDirty ?? true });
+export const windowSettingsOf = (s: ExplorerViewSettings) => ({ sidebarSide: s.window?.sidebarSide ?? 'left' });
+
+const DEFAULT_MAX_ROWS = 1000;
+
+/** The stored Workbench state with every field the Explorer reads filled with its default. */
+export const withWorkbenchDefaults = (raw?: Partial<ExplorerWorkbench>) => ({
+  ...raw,
+  explorerProjects: raw?.explorerProjects ?? [],
+  maxRows: raw?.maxRows ?? DEFAULT_MAX_ROWS,
+  results: { ...DEFAULT_RESULT_FORMAT, ...raw?.results },
+  copyFormat: raw?.copyFormat ?? ('tsv' satisfies CopyFormat),
+  confirmDestructive: raw?.confirmDestructive ?? true,
+  queryTimeout: raw?.queryTimeout ?? 0,
+  format: { ...DEFAULT_FORMAT_OPTIONS, ...raw?.format },
+});
+
+export const sqlRunnerSettings = (s: ReturnType<typeof withWorkbenchDefaults>): SqlRunnerSettings => ({
+  maxRows: s.maxRows,
+  results: s.results,
+  copyFormat: s.copyFormat,
+  confirmDestructive: s.confirmDestructive,
+  queryTimeout: s.queryTimeout,
+});
+
+const explorer: SectionPath = ['explorer'];
+
+/** The `files.*` rows of the Explorer section; the editor's saving rows stay with the app. */
+export const explorerSettingDefs: SettingDef<ExplorerViewSettings>[] = [
+  fileBoolSetting('previewTabs', explorer, 10, 'settings.explorer.previewTabs'),
+  fileBoolSetting('autoReveal', explorer, 20, 'settings.explorer.autoReveal'),
+  fileBoolSetting('breadcrumbs', explorer, 30, 'settings.explorer.breadcrumbs'),
+  fileBoolSetting('compactFolders', explorer, 40, 'settings.explorer.compact'),
+  fileEnumSetting('sortOrder', explorer, 50, 'settings.explorer.sort', SORT_ORDERS),
+  fileBoolSetting('fileNesting', explorer, 60, 'settings.explorer.nesting'),
+  {
+    id: 'files.nestingPatterns',
+    kind: 'custom',
+    section: explorer,
+    order: 70,
+    label: 'settings.explorer.nesting.patterns',
+    description: 'settings.explorer.nesting.patterns.hint',
+    default: FILE_DEFAULTS.nestingPatterns,
+    get: (s) => fileSettingsOf(s.files).nestingPatterns,
+    set: (s, v) => ({ files: { ...fileSettingsOf(s.files), nestingPatterns: v as Record<string, string> } }),
+  },
+  {
+    id: 'files.exclude',
+    kind: 'custom',
+    section: explorer,
+    order: 80,
+    label: 'settings.explorer.exclude',
+    description: 'settings.explorer.exclude.hint',
+    default: FILE_DEFAULTS.exclude,
+    get: (s) => fileSettingsOf(s.files).exclude,
+    set: (s, v) => ({ files: { ...fileSettingsOf(s.files), exclude: v as string[] } }),
+  },
+  fileBoolSetting('confirmDelete', explorer, 90, 'settings.explorer.confirmDelete'),
+  fileBoolSetting('confirmDragDrop', explorer, 100, 'settings.explorer.confirmDragDrop'),
+  fileBoolSetting('showHidden', explorer, 110, 'settings.explorer.showHidden'),
+  fileBoolSetting('restoreTabs', explorer, 120, 'settings.explorer.restoreTabs'),
+  fileBoolSetting('markdownToc', explorer, 130, 'settings.explorer.markdownToc'),
+];

package/src/view.tsx

@@ -0,0 +1,38 @@
+import { lazy } from 'react';
+import { defineView } from '@deckbuilderkit/ui';
+import { bindExplorerClient, type ExplorerClients } from './client';
+import { explorerViewCommands } from './commands';
+import { en, ptBR } from './i18n';
+import { setMultiDelete } from './options';
+import { explorerSettingDefs, type ExplorerViewSettings } from './settings';
+import { ExcludeSettingField, ExplorerCard, NestingSettingField } from './settings/cards';
+
+const ExplorerScreen = lazy(() => import('./ExplorerScreen').then((m) => ({ default: m.ExplorerScreen })));
+
+export interface ExplorerViewOptions {
+  /** i18n key of the nav section title. */
+  group: string;
+  order: number;
+  /** The server calls the screen makes. */
+  client: ExplorerClients;
+  /** Whether the tree may delete several entries at once; off when omitted. */
+  multiDelete?: boolean;
+}
+
+export function explorerView({ group, order, client, multiDelete = false }: ExplorerViewOptions) {
+  bindExplorerClient(client);
+  setMultiDelete(multiDelete);
+  return defineView<'explorer', ExplorerViewSettings, 'nav.explorer'>({
+    id: 'explorer',
+    nav: { group, icon: 'folder', label: 'nav.explorer', order },
+    render: ({ settings, onSave }) => <ExplorerScreen settings={settings} onSave={onSave} />,
+    commands: explorerViewCommands,
+    settings: { defs: explorerSettingDefs },
+    settingsCards: {
+      sections: [{ path: ['explorer'], order: 50, label: 'settings.section.explorer' }],
+      cards: { explorer: ExplorerCard },
+      fields: { 'files.nestingPatterns': NestingSettingField, 'files.exclude': ExcludeSettingField },
+    },
+    messages: { en, 'pt-BR': ptBR },
+  });
+}

package/src/web.ts

@@ -0,0 +1,4 @@
+export { type EditorInfo, type ExplorerClient, type ExplorerClients, type FsEntry, type FsRead, type Project, type SearchHit, type TextEncoding } from './client';
+export { type ExplorerMessageKey } from './i18n';
+export { type ExplorerSettings, type ExplorerViewSettings } from './settings';
+export { explorerView, type ExplorerViewOptions } from './view';