@dropsh/plugin-tui 0.5.3 → 0.5.6

package/dist/plugins/tui/src/browse-app.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+import { useState } from "react";
+import { FocusRegistryProvider, useFocusRegistry } from "./link.js";
+// Inner component: has access to the focus registry so Enter can read the
+// focused link target and ask the router to navigate to it.
+function Keys({ router, onExit, focusedIndex, setFocusedIndex, bump, setError, setNavSeq, }) {
+    const reg = useFocusRegistry();
+    useInput((input, key) => {
+        if (input === "q" || key.escape) {
+            const hasMore = router.back();
+            if (!hasMore)
+                onExit();
+            else {
+                setFocusedIndex(() => 0);
+                setError(null);
+                setNavSeq((n) => n + 1);
+                bump();
+            }
+            return;
+        }
+        if (key.upArrow)
+            setFocusedIndex((i) => Math.max(0, i - 1));
+        if (key.downArrow)
+            setFocusedIndex((i) => Math.min(Math.max(0, reg.count() - 1), i + 1));
+        if (key.return) {
+            const target = reg.targetAt(focusedIndex);
+            if (target) {
+                void router
+                    .navigate(target.route, target.params)
+                    .then(() => {
+                    setFocusedIndex(() => 0);
+                    setError(null);
+                    setNavSeq((n) => n + 1);
+                    bump();
+                })
+                    .catch((err) => {
+                    setError(err instanceof Error ? err.message : String(err));
+                    bump();
+                });
+            }
+        }
+    });
+    return null;
+}
+export function Browse({ router, onExit }) {
+    const [focusedIndex, setFocusedIndex] = useState(0);
+    const [, setNonce] = useState(0);
+    const [error, setError] = useState(null);
+    const [navSeq, setNavSeq] = useState(0);
+    const bump = () => setNonce((n) => n + 1);
+    const element = router.current();
+    return (_jsxs(FocusRegistryProvider, { focusedIndex: focusedIndex, children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { flexDirection: "column", children: element }, navSeq), error !== null ? _jsxs(Text, { color: "red", children: ["Error: ", error] }) : null, _jsx(Text, { dimColor: true, children: "(\u2191/\u2193: move, enter: open, q/esc: back)" })] }), _jsx(Keys, { router: router, onExit: onExit, focusedIndex: focusedIndex, setFocusedIndex: setFocusedIndex, bump: bump, setError: setError, setNavSeq: setNavSeq })] }));
+}

package/dist/plugins/tui/src/entity-list.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { label, splitType } from "./jsonapi-type.js";
+import { TuiLink } from "./link.js";
+export class TuiEntityList {
+    static entityType;
+    static bundle;
+}
+export class GenericEntityList extends TuiEntityList {
+    static entityType = "*";
+    build(resources, ctx) {
+        if (resources.length === 0)
+            return _jsx(Text, { dimColor: true, children: "(no results)" });
+        return (_jsx(Box, { flexDirection: "column", children: resources.map((res) => {
+                const { entityType, bundle } = splitType(res.type);
+                const params = { type: entityType, id: res.id };
+                if (bundle)
+                    params.bundle = bundle;
+                return (_jsx(TuiLink, { target: ctx.link("entity.canonical", params), children: label(res) }, res.id));
+            }) }));
+    }
+}

package/dist/plugins/tui/src/entity-view.js

@@ -0,0 +1,27 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { splitType } from "./jsonapi-type.js";
+import { TuiLink } from "./link.js";
+export class TuiEntityView {
+    static entityType;
+    static bundle;
+    static viewModes = { default: {} };
+}
+export class GenericEntityView extends TuiEntityView {
+    static entityType = "*";
+    static viewModes = { default: {} };
+    build(entity, ctx) {
+        const attrs = entity.attributes ?? {};
+        const rels = entity.relationships ?? {};
+        return (_jsxs(Box, { flexDirection: "column", children: [Object.entries(attrs).map(([key, value]) => (_jsxs(Text, { children: [key, ": ", typeof value === "string" ? value : JSON.stringify(value)] }, `a:${key}`))), Object.entries(rels).map(([key, rel]) => {
+                    const data = rel.data;
+                    if (!data || Array.isArray(data))
+                        return _jsxs(Text, { children: [key, ": \u2014"] }, `r:${key}`);
+                    const { entityType, bundle } = splitType(data.type);
+                    const params = { type: entityType, id: data.id };
+                    if (bundle)
+                        params.bundle = bundle;
+                    return (_jsxs(Box, { children: [_jsxs(Text, { children: [key, ": "] }), _jsx(TuiLink, { target: ctx.link("entity.canonical", params), children: data.id })] }, `r:${key}`));
+                })] }));
+    }
+}

package/dist/plugins/tui/src/index.js

@@ -0,0 +1,61 @@
+import { ConfigError } from "dropsh/plugin";
+import { splitType } from "./jsonapi-type.js";
+import { buildRegistry } from "./registry.js";
+import { createRouter } from "./router.js";
+export { GenericEntityList, TuiEntityList } from "./entity-list.js";
+export { GenericEntityView, TuiEntityView } from "./entity-view.js";
+export { TuiLink } from "./link.js";
+function assertTty(isTty) {
+    if (!isTty)
+        throw new ConfigError("--format tui requires an interactive terminal");
+}
+export function initialTarget(doc, ctx) {
+    if (ctx.command === "search") {
+        const params = { type: ctx.entityType ?? "" };
+        if (ctx.bundle)
+            params.bundle = ctx.bundle;
+        return { route: "entity.collection", params };
+    }
+    const first = (Array.isArray(doc.data) ? doc.data[0] : doc.data);
+    const { entityType, bundle } = splitType(first?.type ?? "");
+    const params = { type: entityType, id: first?.id ?? "" };
+    if (bundle)
+        params.bundle = bundle;
+    return { route: "entity.canonical", params };
+}
+async function runTui(doc, ctx, opts, services) {
+    assertTty(Boolean(process.stdout.isTTY));
+    if (!services)
+        throw new ConfigError("--format tui requires runtime services (client)");
+    const registry = buildRegistry(opts.plugins ?? []);
+    const router = createRouter({
+        registry,
+        client: services.client,
+        viewMode: ctx.viewMode ?? "default",
+    });
+    const target = initialTarget(doc, ctx);
+    await router.navigate(target.route, target.params, doc);
+    const [{ render }, React, { Browse }] = await Promise.all([
+        import("ink"),
+        import("react"),
+        import("./browse-app.js"),
+    ]);
+    const app = render(React.createElement(Browse, { router, onExit: () => app.unmount() }));
+    await app.waitUntilExit();
+}
+export function tuiPlugin(tuiOpts = {}) {
+    return {
+        id: "tui",
+        requiredModules: [],
+        async extendSchema(_entityType, _bundle, schema) {
+            return schema;
+        },
+        renderers: [
+            {
+                id: "tui",
+                interactive: true,
+                run: (doc, ctx, services) => runTui(doc, ctx, tuiOpts, services),
+            },
+        ],
+    };
+}

package/dist/plugins/tui/src/jsonapi-type.js

@@ -0,0 +1,15 @@
+// Splits a JSON:API type "node--article" into { entityType: "node", bundle: "article" }.
+export function splitType(type) {
+    const [entityType, bundle] = type.split("--");
+    return bundle ? { entityType, bundle } : { entityType };
+}
+// Best-effort human label for a resource: first string-valued title/name/label attribute, else id.
+export function label(res) {
+    const attrs = res.attributes ?? {};
+    for (const key of ["title", "name", "label"]) {
+        const v = attrs[key];
+        if (typeof v === "string")
+            return v;
+    }
+    return res.id;
+}

package/dist/plugins/tui/src/link.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from "ink";
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+const Ctx = createContext(null);
+export function useFocusRegistry() {
+    const reg = useContext(Ctx);
+    if (!reg)
+        throw new Error("useFocusRegistry must be used within FocusRegistryProvider");
+    return reg;
+}
+export function FocusRegistryProvider({ focusedIndex = 0, children, }) {
+    const [entries, setEntries] = useState([]);
+    const reg = useMemo(() => ({
+        register(id, target) {
+            setEntries((prev) => (prev.some((e) => e.id === id) ? prev : [...prev, { id, target }]));
+        },
+        unregister(id) {
+            setEntries((prev) => prev.filter((e) => e.id !== id));
+        },
+        indexOf: (id) => entries.findIndex((e) => e.id === id),
+        count: () => entries.length,
+        focusedIndex,
+        targetAt: (i) => entries[i]?.target,
+    }), [entries, focusedIndex]);
+    return _jsx(Ctx.Provider, { value: reg, children: children });
+}
+export function TuiLink({ target, children, }) {
+    const reg = useFocusRegistry();
+    const idRef = useRef(null);
+    if (idRef.current === null)
+        idRef.current = Symbol("tuilink");
+    const id = idRef.current;
+    // Register once on mount, unregister on unmount. A link's target is fixed for
+    // its lifetime (derived from stable entity data), so no per-render update.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: register once on mount only
+    useEffect(() => {
+        reg.register(id, target);
+        return () => reg.unregister(id);
+    }, []);
+    const index = reg.indexOf(id);
+    const isFocused = index === reg.focusedIndex;
+    return _jsx(Text, { inverse: isFocused, children: children });
+}

package/dist/plugins/tui/src/registry.js

@@ -0,0 +1,74 @@
+import { DrupalJsonApiParams } from "drupal-jsonapi-params";
+import React from "react";
+import { GenericEntityList, TuiEntityList } from "./entity-list.js";
+import { GenericEntityView, TuiEntityView } from "./entity-view.js";
+function key(entityType, bundle) {
+    return `${entityType}:${bundle ?? ""}`;
+}
+function isView(c) {
+    return typeof c === "function" && c.prototype instanceof TuiEntityView;
+}
+function isList(c) {
+    return typeof c === "function" && c.prototype instanceof TuiEntityList;
+}
+function buildCtxLink(ctx) {
+    return {
+        viewMode: ctx.viewMode,
+        link: (route, params) => ({ route, params }),
+    };
+}
+function coreRoutes() {
+    const canonical = {
+        name: "entity.canonical",
+        path: "/{type}/{bundle}/{id}",
+        controller: async (params, ctx) => {
+            const ViewClass = ctx.resolveView(params.type, params.bundle);
+            const include = ViewClass?.viewModes?.[ctx.viewMode]?.include;
+            const path = params.bundle
+                ? `${params.type}/${params.bundle}/${params.id}`
+                : `${params.type}/${params.id}`;
+            const doc = (ctx.seededDoc ??
+                (include?.length
+                    ? await ctx.client.get(path, new DrupalJsonApiParams().addInclude(include))
+                    : await ctx.client.get(path)));
+            const entity = (Array.isArray(doc.data) ? doc.data[0] : doc.data);
+            const instance = new ViewClass();
+            return React.createElement(React.Fragment, null, instance.build(entity, { doc, ...buildCtxLink(ctx) }));
+        },
+    };
+    const collection = {
+        name: "entity.collection",
+        path: "/{type}",
+        controller: async (params, ctx) => {
+            const ListClass = ctx.resolveList(params.type, params.bundle);
+            const doc = (ctx.seededDoc ??
+                (await ctx.client.get(params.bundle ? `${params.type}/${params.bundle}` : params.type)));
+            const rows = (Array.isArray(doc.data) ? doc.data : [doc.data]);
+            const instance = new ListClass();
+            return React.createElement(React.Fragment, null, instance.build(rows, { doc, ...buildCtxLink(ctx) }));
+        },
+    };
+    return [canonical, collection];
+}
+export function buildRegistry(plugins) {
+    const views = new Map();
+    const lists = new Map();
+    const routes = new Map();
+    for (const r of coreRoutes())
+        routes.set(r.name, r);
+    for (const p of plugins) {
+        for (const entity of p.entities ?? []) {
+            if (isView(entity))
+                views.set(key(entity.entityType, entity.bundle), entity);
+            else if (isList(entity))
+                lists.set(key(entity.entityType, entity.bundle), entity);
+        }
+        for (const route of p.routes ?? [])
+            routes.set(route.name, route);
+    }
+    return {
+        resolveView: (t, b) => views.get(key(t, b)) ?? views.get(key(t)) ?? GenericEntityView,
+        resolveList: (t, b) => lists.get(key(t, b)) ?? lists.get(key(t)) ?? GenericEntityList,
+        routes,
+    };
+}

package/dist/plugins/tui/src/router.js

@@ -0,0 +1,31 @@
+export function createRouter(opts) {
+    const stack = [];
+    async function navigate(routeName, params, seededDoc) {
+        const route = opts.registry.routes.get(routeName);
+        if (!route)
+            throw new Error(`unknown route: ${routeName}`);
+        const ctx = {
+            client: opts.client,
+            viewMode: opts.viewMode,
+            ...(seededDoc !== undefined ? { seededDoc } : {}),
+            navigate: (r, p) => {
+                // Host-level navigation surfaces errors in the UI; a controller-initiated
+                // navigation failure must not become an unhandled rejection / crash.
+                void navigate(r, p).catch(() => { });
+            },
+            resolveView: opts.registry.resolveView,
+            resolveList: opts.registry.resolveList,
+        };
+        const element = await route.controller(params, ctx);
+        stack.push(element);
+    }
+    return {
+        stackDepth: () => stack.length,
+        current: () => stack[stack.length - 1] ?? null,
+        navigate,
+        back() {
+            stack.pop();
+            return stack.length > 0;
+        },
+    };
+}

package/dist/plugins/tui/src/types.js

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

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@dropsh/plugin-tui",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "type": "module",
   "main": "./dist/plugins/tui/src/index.js",
   "exports": {
     ".": "./dist/plugins/tui/src/index.js"
   },
+  "files": [
+    "dist/plugins/tui/src"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -15,14 +18,14 @@
   "dependencies": {
     "ink": "^5.0.0",
     "react": "^18.3.0",
-    "@dropsh/plugin-markdown": "0.5.3"
+    "@dropsh/plugin-markdown": "0.5.6"
   },
   "devDependencies": {
     "@types/react": "^18.3.0",
     "ink-testing-library": "^4.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0",
-    "dropsh": "0.5.3"
+    "dropsh": "0.5.6"
   },
   "scripts": {
     "build": "tsc",

package/src/browse-app.tsx

@@ -1,94 +0,0 @@
-import { Box, Text, useInput } from "ink";
-import type React from "react";
-import { useState } from "react";
-import { FocusRegistryProvider, useFocusRegistry } from "./link.js";
-import type { Router } from "./router.js";
-
-export interface BrowseProps {
-  router: Router;
-  onExit: () => void;
-}
-
-// Inner component: has access to the focus registry so Enter can read the
-// focused link target and ask the router to navigate to it.
-function Keys({
-  router,
-  onExit,
-  focusedIndex,
-  setFocusedIndex,
-  bump,
-  setError,
-  setNavSeq,
-}: {
-  router: Router;
-  onExit: () => void;
-  focusedIndex: number;
-  setFocusedIndex: (fn: (i: number) => number) => void;
-  bump: () => void;
-  setError: (msg: string | null) => void;
-  setNavSeq: (fn: (n: number) => number) => void;
-}): null {
-  const reg = useFocusRegistry();
-  useInput((input, key) => {
-    if (input === "q" || key.escape) {
-      const hasMore = router.back();
-      if (!hasMore) onExit();
-      else {
-        setFocusedIndex(() => 0);
-        setError(null);
-        setNavSeq((n) => n + 1);
-        bump();
-      }
-      return;
-    }
-    if (key.upArrow) setFocusedIndex((i) => Math.max(0, i - 1));
-    if (key.downArrow) setFocusedIndex((i) => Math.min(Math.max(0, reg.count() - 1), i + 1));
-    if (key.return) {
-      const target = reg.targetAt(focusedIndex);
-      if (target) {
-        void router
-          .navigate(target.route, target.params)
-          .then(() => {
-            setFocusedIndex(() => 0);
-            setError(null);
-            setNavSeq((n) => n + 1);
-            bump();
-          })
-          .catch((err: unknown) => {
-            setError(err instanceof Error ? err.message : String(err));
-            bump();
-          });
-      }
-    }
-  });
-  return null;
-}
-
-export function Browse({ router, onExit }: BrowseProps): React.ReactElement {
-  const [focusedIndex, setFocusedIndex] = useState(0);
-  const [, setNonce] = useState(0);
-  const [error, setError] = useState<string | null>(null);
-  const [navSeq, setNavSeq] = useState(0);
-  const bump = () => setNonce((n) => n + 1);
-  const element = router.current();
-  return (
-    <FocusRegistryProvider focusedIndex={focusedIndex}>
-      <Box flexDirection="column">
-        <Box key={navSeq} flexDirection="column">
-          {element}
-        </Box>
-        {error !== null ? <Text color="red">Error: {error}</Text> : null}
-        <Text dimColor>(↑/↓: move, enter: open, q/esc: back)</Text>
-      </Box>
-      <Keys
-        router={router}
-        onExit={onExit}
-        focusedIndex={focusedIndex}
-        setFocusedIndex={setFocusedIndex}
-        bump={bump}
-        setError={setError}
-        setNavSeq={setNavSeq}
-      />
-    </FocusRegistryProvider>
-  );
-}

package/src/entity-list.tsx

@@ -1,34 +0,0 @@
-import type { JsonApiResource } from "dropsh/plugin";
-import { Box, Text } from "ink";
-import React, { type ReactElement } from "react";
-import { label, splitType } from "./jsonapi-type.js";
-import { TuiLink } from "./link.js";
-import type { BuildContext } from "./types.js";
-
-export abstract class TuiEntityList {
-  static entityType: string;
-  static bundle?: string;
-  abstract build(resources: JsonApiResource[], ctx: BuildContext): ReactElement;
-}
-
-export class GenericEntityList extends TuiEntityList {
-  static override entityType = "*";
-
-  build(resources: JsonApiResource[], ctx: BuildContext): ReactElement {
-    if (resources.length === 0) return <Text dimColor>(no results)</Text>;
-    return (
-      <Box flexDirection="column">
-        {resources.map((res) => {
-          const { entityType, bundle } = splitType(res.type);
-          const params: Record<string, string> = { type: entityType, id: res.id };
-          if (bundle) params.bundle = bundle;
-          return (
-            <TuiLink key={res.id} target={ctx.link("entity.canonical", params)}>
-              {label(res)}
-            </TuiLink>
-          );
-        })}
-      </Box>
-    );
-  }
-}

package/src/entity-view.tsx

@@ -1,45 +0,0 @@
-import type { JsonApiResource } from "dropsh/plugin";
-import { Box, Text } from "ink";
-import React, { type ReactElement } from "react";
-import { splitType } from "./jsonapi-type.js";
-import { TuiLink } from "./link.js";
-import type { BuildContext, ViewModeMap } from "./types.js";
-
-export abstract class TuiEntityView {
-  static entityType: string;
-  static bundle?: string;
-  static viewModes: ViewModeMap = { default: {} };
-  abstract build(entity: JsonApiResource, ctx: BuildContext): ReactElement;
-}
-
-export class GenericEntityView extends TuiEntityView {
-  static override entityType = "*";
-  static override viewModes: ViewModeMap = { default: {} };
-
-  build(entity: JsonApiResource, ctx: BuildContext): ReactElement {
-    const attrs = entity.attributes ?? {};
-    const rels = entity.relationships ?? {};
-    return (
-      <Box flexDirection="column">
-        {Object.entries(attrs).map(([key, value]) => (
-          <Text key={`a:${key}`}>
-            {key}: {typeof value === "string" ? value : JSON.stringify(value)}
-          </Text>
-        ))}
-        {Object.entries(rels).map(([key, rel]) => {
-          const data = (rel as { data?: { type: string; id: string } }).data;
-          if (!data || Array.isArray(data)) return <Text key={`r:${key}`}>{key}: —</Text>;
-          const { entityType, bundle } = splitType(data.type);
-          const params: Record<string, string> = { type: entityType, id: data.id };
-          if (bundle) params.bundle = bundle;
-          return (
-            <Box key={`r:${key}`}>
-              <Text>{key}: </Text>
-              <TuiLink target={ctx.link("entity.canonical", params)}>{data.id}</TuiLink>
-            </Box>
-          );
-        })}
-      </Box>
-    );
-  }
-}

package/src/index.ts

@@ -1,94 +0,0 @@
-import type {
-  DropSHPlugin,
-  JsonApiDocument,
-  JsonApiResource,
-  RenderContext,
-  RenderServices,
-} from "dropsh/plugin";
-import { ConfigError } from "dropsh/plugin";
-import { splitType } from "./jsonapi-type.js";
-import { buildRegistry } from "./registry.js";
-import { createRouter } from "./router.js";
-import type { TuiSubPlugin } from "./types.js";
-
-export { GenericEntityList, TuiEntityList } from "./entity-list.js";
-export { GenericEntityView, TuiEntityView } from "./entity-view.js";
-export { TuiLink } from "./link.js";
-export type {
-  BuildContext,
-  LinkDescriptor,
-  TuiController,
-  TuiRoute,
-  TuiSubPlugin,
-  ViewModeMap,
-} from "./types.js";
-
-export interface TuiOptions {
-  plugins?: TuiSubPlugin[];
-}
-
-function assertTty(isTty: boolean): void {
-  if (!isTty) throw new ConfigError("--format tui requires an interactive terminal");
-}
-
-export function initialTarget(
-  doc: JsonApiDocument,
-  ctx: RenderContext,
-): {
-  route: string;
-  params: Record<string, string>;
-} {
-  if (ctx.command === "search") {
-    const params: Record<string, string> = { type: ctx.entityType ?? "" };
-    if (ctx.bundle) params.bundle = ctx.bundle;
-    return { route: "entity.collection", params };
-  }
-  const first = (Array.isArray(doc.data) ? doc.data[0] : doc.data) as JsonApiResource | undefined;
-  const { entityType, bundle } = splitType(first?.type ?? "");
-  const params: Record<string, string> = { type: entityType, id: first?.id ?? "" };
-  if (bundle) params.bundle = bundle;
-  return { route: "entity.canonical", params };
-}
-
-async function runTui(
-  doc: JsonApiDocument,
-  ctx: RenderContext,
-  opts: TuiOptions,
-  services?: RenderServices,
-): Promise<void> {
-  assertTty(Boolean(process.stdout.isTTY));
-  if (!services) throw new ConfigError("--format tui requires runtime services (client)");
-  const registry = buildRegistry(opts.plugins ?? []);
-  const router = createRouter({
-    registry,
-    client: services.client,
-    viewMode: ctx.viewMode ?? "default",
-  });
-  const target = initialTarget(doc, ctx);
-  await router.navigate(target.route, target.params, doc);
-
-  const [{ render }, React, { Browse }] = await Promise.all([
-    import("ink"),
-    import("react"),
-    import("./browse-app.js"),
-  ]);
-  const app = render(React.createElement(Browse, { router, onExit: () => app.unmount() }));
-  await app.waitUntilExit();
-}
-
-export function tuiPlugin(tuiOpts: TuiOptions = {}): DropSHPlugin {
-  return {
-    id: "tui",
-    requiredModules: [],
-    async extendSchema(_entityType, _bundle, schema) {
-      return schema;
-    },
-    renderers: [
-      {
-        id: "tui",
-        interactive: true,
-        run: (doc, ctx, services) => runTui(doc, ctx, tuiOpts, services),
-      },
-    ],
-  };
-}

package/src/jsonapi-type.ts

@@ -1,17 +0,0 @@
-import type { JsonApiResource } from "dropsh/plugin";
-
-// Splits a JSON:API type "node--article" into { entityType: "node", bundle: "article" }.
-export function splitType(type: string): { entityType: string; bundle?: string } {
-  const [entityType, bundle] = type.split("--") as [string, string?];
-  return bundle ? { entityType, bundle } : { entityType };
-}
-
-// Best-effort human label for a resource: first string-valued title/name/label attribute, else id.
-export function label(res: JsonApiResource): string {
-  const attrs = res.attributes ?? {};
-  for (const key of ["title", "name", "label"]) {
-    const v = attrs[key];
-    if (typeof v === "string") return v;
-  }
-  return res.id;
-}