@devix-tecnologia/directus-extension-mapgrid 1.5.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devix-tecnologia/directus-extension-mapgrid",
-  "version": "1.5.1",
+  "version": "2.0.0",
   "description": "Extension for show map and grid list on Layout Directus",
   "icon": "extension",
   "keywords": [
@@ -30,8 +30,8 @@
     "url": "https://github.com/devix-tecnologia/directus-extension-mapgrid"
   },
   "engines": {
-    "node": ">=20.0.0",
-    "pnpm": ">=10.0.0"
+    "node": ">=22.13.1",
+    "pnpm": ">=10.15.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -39,9 +39,16 @@
   },
   "files": [
     "dist/",
+    "src/contract/",
     "package.json",
     "pnpm-lock.yaml"
   ],
+  "exports": {
+    "./contract": {
+      "types": "./src/contract/index.ts",
+      "import": "./src/contract/index.ts"
+    }
+  },
   "directus:extension": {
     "type": "layout",
     "path": "dist/index.js",
@@ -58,51 +65,82 @@
   "scripts": {
     "build": "directus-extension build",
     "dev": "directus-extension build -w --no-minify",
+    "validate": "directus-extension validate",
     "link": "directus-extension link",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint \"src/**/*.{ts,vue}\"",
-    "lint:fix": "eslint \"src/**/*.{ts,vue}\" --fix",
-    "format": "prettier --write src/",
-    "prepare": "husky"
+    "typecheck": "vue-tsc --noEmit && tsc --noEmit -p tsconfig.tests.json",
+    "lint": "biome check",
+    "lint:fix": "biome check --write --unsafe",
+    "format": "biome format --write src/",
+    "prepare": "husky",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "check:stories": "playwright test --config=playwright.stories.config.ts",
+    "test": "vitest run && vitest run --config vitest.directus-vue.config.ts",
+    "test:watch": "vitest",
+    "test:integration": "VERBOSE=true node --disable-warning=ExperimentalWarning --experimental-strip-types tests/run-docker-tests.js integration",
+    "test:e2e": "pnpm build && VERBOSE=true node --disable-warning=ExperimentalWarning --experimental-strip-types tests/run-docker-tests.js e2e",
+    "test:e2e:docker": "pnpm test:e2e",
+    "test:e2e:host": "pnpm build && VERBOSE=true node --disable-warning=ExperimentalWarning --experimental-strip-types tests/run-docker-tests.js e2e --host",
+    "screenshot": "pnpm build && docker compose -f docker-compose.test.yml --profile runner run --rm -e RUNNER_CMD=screenshot tests; status=$?; docker compose -f docker-compose.test.yml --profile runner down --remove-orphans; exit $status",
+    "test:e2e:ui": "pnpm build && VERBOSE=true node --disable-warning=ExperimentalWarning --experimental-strip-types tests/run-docker-tests.js e2e --host -- --ui",
+    "test:e2e:record": "pnpm build && VERBOSE=true node --disable-warning=ExperimentalWarning --experimental-strip-types tests/run-docker-tests.js e2e --host -- --config=playwright.record.config.ts",
+    "test:e2e:record:head": "pnpm test:e2e:record && pnpm exec playwright show-report playwright-report",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:report": "playwright show-report",
+    "test:collection": "node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/test-collection.ts",
+    "demo": "node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/demo.ts",
+    "test:all": "pnpm test && pnpm test:integration && pnpm test:e2e",
+    "sandcastle": "node --disable-warning=ExperimentalWarning --experimental-strip-types .sandcastle/main.ts",
+    "sandcastle:round": "node --disable-warning=ExperimentalWarning --experimental-strip-types .sandcastle/round.ts",
+    "sandcastle:queue": "node --disable-warning=ExperimentalWarning --experimental-strip-types .sandcastle/task-queue/cli.ts",
+    "sandcastle:image": "docker build -t sandcastle:$(basename \"$PWD\" | tr '[:upper:]' '[:lower:]') --build-arg AGENT_UID=$(id -u) --build-arg AGENT_GID=$(id -g) --build-arg DOCKER_GID=$(getent group docker | cut -d: -f3) -f .sandcastle/Dockerfile .sandcastle",
+    "sandcastle:clean": "node .sandcastle/clean-worktrees.mjs",
+    "typecheck:sandcastle": "tsc --noEmit -p .sandcastle/tsconfig.json",
+    "test:directus-vue": "vitest run --config vitest.directus-vue.config.ts",
+    "sandcastle:round:authenticated": "node --disable-warning=ExperimentalWarning --experimental-strip-types .sandcastle/authenticated-round.ts"
   },
   "devDependencies": {
-    "@directus/extensions-sdk": "^13.0.3",
-    "@directus/types": "^13.0.0",
-    "@eslint/js": "^9.21.0",
+    "@ai-hero/sandcastle": "^0.12.0",
+    "@biomejs/biome": "^2.5.9",
+    "@directus/constants": "^13.0.3",
+    "@directus/extensions-sdk": "^16.0.2",
+    "@directus/types": "^13.2.3",
+    "@playwright/test": "^1.62.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.1",
-    "@semantic-release/npm": "^12.0.1",
-    "@types/maplibre-gl": "^1.14.0",
-    "@typescript-eslint/eslint-plugin": "^8.26.0",
-    "@typescript-eslint/parser": "^8.26.0",
-    "@vue/eslint-config-typescript": "^14.4.0",
-    "eslint": "^9.21.0",
-    "eslint-config-prettier": "^10.0.2",
-    "eslint-plugin-vue": "^9.33.0",
-    "globals": "^15.15.0",
+    "@semantic-release/github": "^12.0.10",
+    "@semantic-release/npm": "^13.2.0",
+    "@storybook/addon-docs": "^10.5.10",
+    "@storybook/vue3-vite": "^10.5.10",
+    "@types/node": "^26.2.0",
+    "@vitejs/plugin-vue": "^6.0.4",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vue/test-utils": "^2.4.11",
+    "axios": "^1.19.0",
+    "directus-vue": "npm:vue@3.4.27",
+    "globals": "^16.4.0",
+    "happy-dom": "^20.11.6",
     "husky": "^9.1.7",
-    "lint-staged": "^15.4.3",
-    "prettier": "^3.5.3",
-    "semantic-release": "^24.2.3",
-    "typescript": "^5.8.2",
-    "vue": "^3.5.13",
-    "vue-eslint-parser": "^9.4.3"
+    "lint-staged": "^16.2.3",
+    "playwright": "^1.62.1",
+    "semantic-release": "^25.0.9",
+    "storybook": "^10.5.10",
+    "storytype": "^0.2.6",
+    "taskin": "^4.4.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "vue": "^3.5.22",
+    "vue-i18n": "^11.4.10",
+    "vue-router": "4.5.1",
+    "vue-tsc": "^3.3.11"
   },
   "dependencies": {
     "@types/geojson": "^7946.0.16",
-    "maplibre-gl": "^5.2.0"
-  },
-  "prettier": {
-    "singleQuote": true,
-    "trailingComma": "es5",
-    "printWidth": 100,
-    "semi": true,
-    "tabWidth": 2
+    "maplibre-gl": "^5.8.0"
   },
   "lint-staged": {
     "*.{ts,vue}": [
-      "eslint --fix",
-      "prettier --write"
+      "biome check --write"
     ]
   },
   "release": {

package/src/contract/camera-tracking.contract.ts

@@ -0,0 +1,14 @@
+/**
+ * How much the camera chases the current record.
+ *
+ * It lives in the contract because it is stored in the Directus preset: a map
+ * implementing `IMapCenterer` has to read the same three states.
+ *
+ * Navigation apps call this *follow mode*; the name "autofocus" was dropped on
+ * purpose, because in photography it is lens sharpness, not framing.
+ *
+ * - `off` — the map stays where the person left it;
+ * - `follow` — moves only when the record leaves the visible area;
+ * - `center` — keeps the record in the middle at every step.
+ */
+export type CameraTracking = 'off' | 'follow' | 'center';

package/src/contract/geolocation.contract.ts

@@ -0,0 +1,5 @@
+/** An item of the collection, as the Directus API returns it. */
+export interface GeoItem {
+  id: string | number;
+  [key: string]: unknown;
+}

package/src/contract/index.ts

@@ -0,0 +1,4 @@
+export * from './camera-tracking.contract';
+export * from './geolocation.contract';
+export * from './layout-options.contract';
+export * from './layout-query';

package/src/contract/layout-options.contract.ts

@@ -0,0 +1,54 @@
+import type { CameraTracking } from './camera-tracking.contract';
+
+/**
+ * Where the current record's arrow takes its direction from.
+ *
+ * - `off` — no arrow;
+ * - `field` — a numeric field of the record, in degrees clockwise from north;
+ * - `computed` — the bearing from the record visited before to the current one.
+ */
+export type HeadingSource = 'off' | 'field' | 'computed';
+
+/**
+ * How long playback waits between records.
+ *
+ * - `fixed` — the same `playbackInterval` for every step;
+ * - `realtime` — the time between the records' own instants, sped up by `playbackSpeed`.
+ */
+export type PlaybackTiming = 'fixed' | 'realtime';
+
+/** What the MapGrid stores in the Directus preset. */
+export interface LayoutOptions {
+  /** The embedded tabular layout's configuration; the content is Directus'. */
+  tabular?: Record<string, unknown>;
+  /** The embedded map layout's configuration; the content is Directus'. */
+  map?: Record<string, unknown>;
+  /** Zoom the map in when a record is focused, instead of keeping the zoom. */
+  zoomOnClick?: boolean;
+  /** How much the camera chases the current record. */
+  cameraTracking?: CameraTracking;
+  /** Seconds between records during playback. */
+  playbackInterval?: number;
+  /** Fixed beat, or the data's own clock. */
+  playbackTiming?: PlaybackTiming;
+  /** How many times faster than the data's clock, in `realtime`. */
+  playbackSpeed?: number;
+  /** The date/time field the data's clock is read from; empty, the sort's is suggested. */
+  playbackTimeField?: string;
+  /** Where the current record's arrow takes its direction from. */
+  headingSource?: HeadingSource;
+  /** The numeric field read when `headingSource` is `field`. */
+  headingField?: string;
+  /** How many visited records the trail joins; `0` turns it off. */
+  trailLength?: number;
+  /** Shows the focused record in a card over the map. */
+  showCard?: boolean;
+  /** The file field whose image the card shows and enlarges. */
+  cardImageField?: string;
+  /** The fields the card lists; empty, it lists the grid's columns. */
+  cardFields?: string[];
+  /** Opens the tour of the features on the first visit of each browser. */
+  tourOnFirstVisit?: boolean;
+  /** The map's share of the height, against the grid's; the rest is the grid's. */
+  mapShare?: number;
+}

package/src/contract/layout-query.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { ref } from 'vue';
+import type { LayoutQuery } from '../types';
+import { useWritableLayoutQuery } from './layout-query';
+
+const queryRef = (initial: Partial<LayoutQuery> | null = null) =>
+  ref(initial as LayoutQuery | null);
+
+describe('useWritableLayoutQuery — reading', () => {
+  it('falls back to the first page when the preset has none', () => {
+    expect(useWritableLayoutQuery(queryRef()).page.value).toBe(1);
+  });
+
+  it('falls back to a page size of 25, which is what Directus itself defaults to', () => {
+    expect(useWritableLayoutQuery(queryRef()).limit.value).toBe(25);
+  });
+
+  it('falls back to no sort, and not to an arbitrary field', () => {
+    expect(useWritableLayoutQuery(queryRef()).sort.value).toEqual([]);
+  });
+
+  it('reads what the preset stored', () => {
+    const query = useWritableLayoutQuery(queryRef({ page: 3, limit: 50, sort: ['-name'] }));
+
+    expect(query.page.value).toBe(3);
+    expect(query.limit.value).toBe(50);
+    expect(query.sort.value).toEqual(['-name']);
+  });
+});
+
+describe('useWritableLayoutQuery — fields is where Directus keeps the displayed columns', () => {
+  it('reads the stored fields', () => {
+    expect(useWritableLayoutQuery(queryRef({ fields: ['name', 'city'] })).fields.value).toEqual([
+      'name',
+      'city',
+    ]);
+  });
+
+  it('returns undefined when nothing was stored, so the caller can fall back', () => {
+    expect(useWritableLayoutQuery(queryRef()).fields.value).toBeUndefined();
+  });
+
+  it('writes the fields back, which is what choosing a column has to persist', () => {
+    const source = queryRef({ page: 1 });
+    useWritableLayoutQuery(source).fields.value = ['name', 'status'];
+
+    expect(source.value?.fields).toEqual(['name', 'status']);
+  });
+});
+
+describe('useWritableLayoutQuery — writing', () => {
+  it('writes the page back to the preset, so pagination survives a reload', () => {
+    const source = queryRef({ page: 1, limit: 25 });
+    useWritableLayoutQuery(source).page.value = 4;
+
+    expect(source.value?.page).toBe(4);
+  });
+
+  it('writes the sort back, which is what clicking a column header needs', () => {
+    const source = queryRef({ page: 1 });
+    useWritableLayoutQuery(source).sort.value = ['-status'];
+
+    expect(source.value?.sort).toEqual(['-status']);
+  });
+
+  it('preserves the other fields when writing one, instead of replacing the preset', () => {
+    const source = queryRef({ page: 2, limit: 50, sort: ['name'], search: 'abc' });
+    useWritableLayoutQuery(source).page.value = 3;
+
+    expect(source.value).toMatchObject({ page: 3, limit: 50, sort: ['name'], search: 'abc' });
+  });
+
+  it('writes onto an absent preset instead of throwing, which is the state of a fresh layout', () => {
+    const source = queryRef(null);
+    useWritableLayoutQuery(source).sort.value = ['name'];
+
+    expect(source.value?.sort).toEqual(['name']);
+  });
+});

package/src/contract/layout-query.ts

@@ -0,0 +1,65 @@
+import { computed, type Ref, type WritableComputedRef } from 'vue';
+import type { LayoutQuery } from '../types';
+
+/**
+ * The parts of the layout query the extension both reads and writes.
+ *
+ * Pagination and sorting are not display preferences: they belong to the query
+ * the layout hands Directus, and they have to survive a reload. Keeping them as
+ * read-only computeds meant the grid could show a sortable header that wrote
+ * nowhere, and the map had no way to advance the page on its own.
+ *
+ * Extracted from the layout's `setup` so it can be tested with a plain ref,
+ * without the Directus composables.
+ */
+
+/** What Directus itself defaults a layout's page size to. */
+const DEFAULT_LIMIT = 25;
+
+export interface WritableLayoutQuery {
+  page: WritableComputedRef<number>;
+  limit: WritableComputedRef<number>;
+  sort: WritableComputedRef<string[]>;
+  /**
+   * The columns the grid shows.
+   *
+   * This lives in the query, and not in the layout options, because that is
+   * where Directus itself keeps it — its tabular layout stores the displayed
+   * columns in `layoutQuery.fields` and derives what to actually fetch from
+   * them. Undefined means nothing was chosen, so the caller can fall back to a
+   * legacy preset or to what it detected from the collection.
+   */
+  fields: WritableComputedRef<string[] | undefined>;
+}
+
+export const useWritableLayoutQuery = (
+  layoutQuery: Ref<LayoutQuery | null | undefined>
+): WritableLayoutQuery => {
+  /**
+   * Writes one field without disturbing the rest. The preset also carries
+   * `filter`, `search` and `fields`, and replacing the object would drop
+   * whatever this layout did not set.
+   */
+  const write = <Key extends keyof LayoutQuery>(key: Key, value: LayoutQuery[Key]): void => {
+    layoutQuery.value = { ...(layoutQuery.value ?? ({} as LayoutQuery)), [key]: value };
+  };
+
+  return {
+    page: computed({
+      get: () => layoutQuery.value?.page || 1,
+      set: (value) => write('page', value),
+    }),
+    limit: computed({
+      get: () => layoutQuery.value?.limit || DEFAULT_LIMIT,
+      set: (value) => write('limit', value),
+    }),
+    sort: computed({
+      get: () => layoutQuery.value?.sort ?? [],
+      set: (value) => write('sort', value),
+    }),
+    fields: computed({
+      get: () => layoutQuery.value?.fields,
+      set: (value) => write('fields', value ?? []),
+    }),
+  };
+};