@_linked/shape-ui 2.0.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_linked/shape-ui",
-  "description": "Shape-driven UI: components that take a shape and a property shape and render an editor for any shape, rather than a known one. Built on @_linked/primitives.",
+  "description": "UI driven by a shape: editors, a table over any shape's instances, a form derived from its properties, a read-only view and a relation picker — plus the read and write paths through the Linked Query DSL.",
   "author": {
     "name": "",
     "email": "",
@@ -8,18 +8,19 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/linked-cm/ui.git"
+    "url": "git+https://github.com/linked-fw/shape-ui.git"
   },
-  "version": "2.0.0",
+  "version": "2.3.0",
+  "type": "module",
   "linkedPackage": true,
-  "main": "lib/index.js",
-  "types": "dist/lincd-ui.d.ts",
+  "main": "lib/esm/index.js",
+  "types": "lib/esm/index.d.ts",
   "license": "ISC",
   "scripts": {
     "start": "npm exec linked dev",
     "build": "rimraf ./lib && yarn build-esm && yarn copy-to-lib",
-    "build-esm": "echo \"compiling ESM\" && rimraf ./lib/esm && (yarn tsc -p tsconfig-esm.json || echo 'tsc returned non-zero; .js still emitted via noEmitOnError default')",
-    "copy-to-lib": "echo 'copying CSS + JSON assets to lib folder' && yarn copyfiles -u 1 'src/**/*.css' 'src/**/*.json' lib/esm"
+    "build-esm": "echo \"compiling ESM\" && rimraf ./lib/esm && tsc -p tsconfig-esm.json",
+    "copy-to-lib": "echo 'copying CSS + JSON assets to lib folder' && copyfiles -u 1 'src/**/*.css' 'src/**/*.json' lib/esm"
   },
   "keywords": [
     "lincd",
@@ -29,19 +30,25 @@
     "web3"
   ],
   "dependencies": {
-    "@_linked/core": "^2.0.1",
-    "@_linked/primitives": "^1.0",
-    "@_linked/react": "^1.2",
+    "@_linked/core": "^2.18.1",
+    "@_linked/react": "^1.4",
     "@_linked/schema": "^1.0",
-    "@_linked/server": "^2.0"
+    "@tanstack/react-table": "^8.20.5"
   },
   "devDependencies": {
     "@_linked/cli": "^1.2",
+    "@_linked/css": "^0.3.0",
+    "@_linked/icons": "^1.0.0",
+    "@_linked/primitives": "^1.2.0",
     "@capacitor/core": "^5.3.0",
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
     "@types/node": "^20.14.9",
+    "@types/react": "^18.0.17",
     "copyfiles": "^2.4.1",
+    "framer-motion": "^12.0.0",
+    "react": "^18.2",
+    "react-dom": "^18.2",
     "rimraf": "^5.0.7",
     "tsconfig-to-dual-package": "^1.2.0",
     "typescript": "^5.7.3",
@@ -50,17 +57,24 @@
   "module": "lib/esm/index.js",
   "exports": {
     ".": {
+      "development": "./src/index.ts",
       "types": "./lib/esm/index.d.ts",
-      "import": "./lib/esm/index.js"
+      "import": "./lib/esm/index.js",
+      "default": "./lib/esm/index.js"
     },
-    "./*.js": {
-      "types": "./lib/esm/*.d.ts",
-      "import": "./lib/esm/*.js"
+    "./components/*": {
+      "development": "./src/components/*.tsx",
+      "types": "./lib/esm/components/*.d.ts",
+      "import": "./lib/esm/components/*.js",
+      "default": "./lib/esm/components/*.js"
     },
     "./*": {
+      "development": "./src/*.ts",
       "types": "./lib/esm/*.d.ts",
-      "import": "./lib/esm/*.js"
-    }
+      "import": "./lib/esm/*.js",
+      "default": "./lib/esm/*.js"
+    },
+    "./tokens.css": "./src/tokens.css"
   },
   "typesVersions": {
     "*": {
@@ -71,5 +85,17 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "peerDependencies": {
+    "@_linked/css": "^0.3.0",
+    "@_linked/icons": "^1.0.0",
+    "@_linked/primitives": "^1.2.0",
+    "framer-motion": ">=11",
+    "react": "^18 || ^19"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md"
+  ]
 }

package/src/backend.ts

@@ -0,0 +1 @@
+//import your providers here (providers only run in the backend)

package/src/columns.regression.test.ts

@@ -0,0 +1,143 @@
+import {describe, expect, test} from '@jest/globals';
+import type {
+  NodeShapeWire,
+  PropertyShapeWire,
+} from '@_linked/core/shapes/nodeShapeWire';
+import {columnsFor, displayableProperties} from './columns.js';
+
+/**
+ * Regression guard for review finding 13.
+ *
+ * The first version of `columnsFor` treated every context like a narrow cell: a property
+ * with a `valueShape`, a `maxCount` other than 1, or a long-text datatype was excluded
+ * outright. Wired into the CMS table that silently deleted every relation column (author,
+ * category, tags — the ones `NodeBadge` and the click-through exist to render), every
+ * multi-valued column, and every long-text column.
+ *
+ * The rule these tests pin: **what fits depends on how much room there is.** A cell shows
+ * one short scalar. A table can show a badge for a related node and a list of them. `full`
+ * shows everything the shape does not hide.
+ */
+
+const base = 'https://example.org/';
+
+function prop(
+  label: string,
+  extra: Partial<PropertyShapeWire> = {},
+): PropertyShapeWire {
+  return {
+    id: `${base}shape/Article/${label}`,
+    label,
+    path: {id: `${base}vocab#${label}`},
+    ...extra,
+  } as PropertyShapeWire;
+}
+
+const article = (): NodeShapeWire =>
+  ({
+    id: `${base}shape/Article`,
+    label: 'Article',
+    targetClass: {id: `${base}vocab#Article`},
+    propertyShapes: [
+      prop('title'),
+      prop('author', {valueShape: {id: `${base}shape/Person`}}),
+      prop('category', {class: {id: `${base}vocab#Category`}}),
+      prop('tags', {maxCount: 0}),
+      prop('body', {
+        datatype: {id: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#HTML'},
+      }),
+      prop('status', {in: [{id: `${base}vocab#Draft`}, {id: `${base}vocab#Live`}]}),
+      prop('internal', {displayHidden: true}),
+    ],
+  }) as NodeShapeWire;
+
+describe('finding 13 — a table keeps the columns a cell cannot hold', () => {
+  test('relation columns survive in a table', () => {
+    const keys = columnsFor(article(), 'table', Infinity).map((c) => c.key);
+    expect(keys).toContain('author'); // sh:node
+    expect(keys).toContain('category'); // sh:class
+  });
+
+  test('multi-valued columns survive in a table', () => {
+    expect(columnsFor(article(), 'table', Infinity).map((c) => c.key)).toContain(
+      'tags',
+    );
+  });
+
+  test('long-text columns survive in `full`, which is what a detail view uses', () => {
+    expect(columnsFor(article(), 'full').map((c) => c.key)).toContain('body');
+  });
+
+  test('enum columns survive', () => {
+    expect(columnsFor(article(), 'table', Infinity).map((c) => c.key)).toContain(
+      'status',
+    );
+  });
+
+  test('a hidden property is still excluded everywhere', () => {
+    for (const context of ['cell', 'card', 'table', 'full'] as const) {
+      expect(columnsFor(article(), context, Infinity).map((c) => c.key)).not.toContain(
+        'internal',
+      );
+    }
+  });
+
+  test('a cell still shows one short scalar, not a relation or a blob', () => {
+    // The narrow case is the one the original rule was written for, and it stays.
+    const cell = columnsFor(article(), 'cell');
+    expect(cell).toHaveLength(1);
+    expect(cell[0].key).toBe('title');
+  });
+
+  test('a cell-sized label is never a relation, even when nothing else qualifies', () => {
+    const relationsOnly = {
+      id: `${base}shape/Only`,
+      label: 'Only',
+      targetClass: {id: `${base}vocab#Only`},
+      propertyShapes: [prop('author', {valueShape: {id: `${base}shape/Person`}})],
+    } as NodeShapeWire;
+    expect(columnsFor(relationsOnly, 'cell')).toHaveLength(0);
+  });
+
+  test('displayableProperties is context-aware, not one fixed answer', () => {
+    // An enum is a short scalar, so it fits a cell too.
+    expect(displayableProperties(article(), 'cell').map((p) => p.label)).toEqual([
+      'title',
+      'status',
+    ]);
+    expect(displayableProperties(article(), 'full').map((p) => p.label)).toEqual([
+      'title',
+      'author',
+      'category',
+      'tags',
+      'body',
+      'status',
+    ]);
+  });
+});
+
+describe('finding 16 — the declared comparator is well defined', () => {
+  test('two properties that declare nothing compare as equal, not NaN', () => {
+    // `Infinity - Infinity` is NaN, which makes a comparator inconsistent. V8 happens to
+    // treat NaN as "equal", so this passed by luck rather than by definition.
+    const shape = {
+      id: `${base}shape/Plain`,
+      label: 'Plain',
+      targetClass: {id: `${base}vocab#Plain`},
+      propertyShapes: [prop('b'), prop('a')],
+    } as NodeShapeWire;
+    const keys = columnsFor(shape, 'full').map((c) => c.key);
+    expect(keys).toHaveLength(2);
+    expect(keys).toEqual(expect.arrayContaining(['a', 'b']));
+  });
+
+  test('a declared rank still beats an undeclared one', () => {
+    const shape = {
+      id: `${base}shape/Mixed`,
+      label: 'Mixed',
+      targetClass: {id: `${base}vocab#Mixed`},
+      propertyShapes: [prop('plain'), prop('ranked', {displayRank: 5})],
+    } as NodeShapeWire;
+    expect(columnsFor(shape, 'full').map((c) => c.key)).toEqual(['ranked', 'plain']);
+  });
+});

package/src/columns.test.ts

@@ -0,0 +1,200 @@
+import {describe, expect, test} from '@jest/globals';
+import type {
+  NodeShapeWire,
+  PropertyShapeWire,
+} from '@_linked/core/shapes/nodeShapeWire';
+import {
+  columnsFor,
+  displayableProperties,
+  hasDeclaredRanks,
+  labelProperty,
+} from './columns.js';
+
+const base = 'https://example.org/';
+
+function prop(
+  label: string,
+  extra: Partial<PropertyShapeWire> = {},
+): PropertyShapeWire {
+  return {
+    id: `${base}shape/Thing/${label}`,
+    label,
+    path: {id: `${base}vocab#${label}`},
+    ...extra,
+  } as PropertyShapeWire;
+}
+
+function shape(props: PropertyShapeWire[]): NodeShapeWire {
+  return {
+    id: `${base}shape/Thing`,
+    label: 'Thing',
+    targetClass: {id: `${base}vocab#Thing`},
+    propertyShapes: props,
+  } as NodeShapeWire;
+}
+
+describe('declared metadata wins', () => {
+  test('displayRank orders the columns', () => {
+    const s = shape([
+      prop('zeta', {displayRank: 3}),
+      prop('alpha', {displayRank: 1}),
+      prop('beta', {displayRank: 2}),
+    ]);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual([
+      'alpha',
+      'beta',
+      'zeta',
+    ]);
+  });
+
+  test('the lowest declared rank is the label column', () => {
+    const s = shape([prop('sku', {displayRank: 2}), prop('title', {displayRank: 1})]);
+    expect(labelProperty(s)?.label).toBe('title');
+    expect(columnsFor(s, 'full')[0]).toMatchObject({key: 'title', isLabel: true});
+  });
+
+  test('displayRank beats a conventional label predicate', () => {
+    // rdfs:label would otherwise win outright. An explicit rank is a first-party
+    // statement and has to outrank a convention.
+    const s = shape([
+      prop('name', {path: {id: 'http://www.w3.org/2000/01/rdf-schema#label'}}),
+      prop('code', {displayRank: 1}),
+    ]);
+    expect(labelProperty(s)?.label).toBe('code');
+  });
+
+  test('displayHidden removes a property entirely, even a required one', () => {
+    const s = shape([
+      prop('secret', {displayHidden: true, minCount: 1}),
+      prop('title'),
+    ]);
+    expect(displayableProperties(s).map((p) => p.label)).toEqual(['title']);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual(['title']);
+  });
+
+  test('sh:order breaks ties between equally ranked properties', () => {
+    const s = shape([
+      prop('b', {displayRank: 1, order: 2}),
+      prop('a', {displayRank: 1, order: 1}),
+    ]);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual(['a', 'b']);
+  });
+
+  test('unranked properties sort after ranked ones', () => {
+    const s = shape([prop('plain'), prop('ranked', {displayRank: 1})]);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual(['ranked', 'plain']);
+  });
+});
+
+describe('heuristics, only where nothing is declared', () => {
+  test('a conventional label predicate is the label', () => {
+    const s = shape([
+      prop('sku'),
+      prop('title', {path: {id: 'http://schema.org/name'}}),
+    ]);
+    expect(labelProperty(s)?.label).toBe('title');
+  });
+
+  test('a name-ish property is the label when no convention matches', () => {
+    const s = shape([prop('quantity'), prop('productTitle')]);
+    expect(labelProperty(s)?.label).toBe('productTitle');
+  });
+
+  test('required properties outrank optional ones', () => {
+    const s = shape([prop('optional'), prop('mandatory', {minCount: 1})]);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual([
+      'mandatory',
+      'optional',
+    ]);
+  });
+
+  test('hasDeclaredRanks reports which regime applies', () => {
+    expect(hasDeclaredRanks(shape([prop('a')]))).toBe(false);
+    expect(hasDeclaredRanks(shape([prop('a', {displayRank: 1})]))).toBe(true);
+  });
+});
+
+describe('what cannot go in a cell', () => {
+  // These assert the CELL rule specifically. They used to assert it at `full`, which
+  // encoded the bug in review finding 13: applying the narrowest rule everywhere deleted
+  // relation, multi-valued and long-text columns from tables too.
+  test('a related node is not a cell', () => {
+    const s = shape([
+      prop('title'),
+      prop('author', {valueShape: {id: `${base}shape/Person`}}),
+    ]);
+    expect(columnsFor(s, 'cell').map((c) => c.key)).toEqual(['title']);
+    // …but a table shows it.
+    expect(columnsFor(s, 'table').map((c) => c.key)).toContain('author');
+  });
+
+  test('an unbounded property is not a cell — a cell cannot show a list', () => {
+    const s = shape([prop('title'), prop('tags', {maxCount: 0})]);
+    expect(columnsFor(s, 'cell').map((c) => c.key)).toEqual(['title']);
+    expect(columnsFor(s, 'table').map((c) => c.key)).toContain('tags');
+  });
+
+  test('long-text datatypes are excluded from every context but `full`', () => {
+    const s = shape([
+      prop('title'),
+      prop('body', {
+        datatype: {id: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#HTML'},
+      }),
+    ]);
+    expect(columnsFor(s, 'table').map((c) => c.key)).toEqual(['title']);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toContain('body');
+  });
+
+  test('a property with no label is skipped — the row key would be undefined', () => {
+    const s = shape([prop('title'), {...prop('x'), label: ''} as PropertyShapeWire]);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual(['title']);
+  });
+});
+
+describe('context limits', () => {
+  const many = shape(
+    ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'].map((l, i) =>
+      prop(l, {displayRank: i + 1}),
+    ),
+  );
+
+  test('each context takes the top N by declared precedence', () => {
+    expect(columnsFor(many, 'cell')).toHaveLength(1);
+    expect(columnsFor(many, 'card')).toHaveLength(3);
+    expect(columnsFor(many, 'table')).toHaveLength(6);
+    expect(columnsFor(many, 'full')).toHaveLength(8);
+  });
+
+  test('the cell context keeps the label', () => {
+    expect(columnsFor(many, 'cell')[0]).toMatchObject({key: 'a', isLabel: true});
+  });
+
+  test('an explicit limit overrides the context', () => {
+    expect(columnsFor(many, 'table', 2).map((c) => c.key)).toEqual(['a', 'b']);
+  });
+});
+
+describe('degenerate shapes', () => {
+  test('a shape with no properties yields no columns and no label', () => {
+    const s = shape([]);
+    expect(columnsFor(s, 'full')).toEqual([]);
+    expect(labelProperty(s)).toBeUndefined();
+  });
+
+  test('a shape with nothing showable yields no label rather than guessing', () => {
+    const s = shape([prop('author', {valueShape: {id: `${base}shape/Person`}})]);
+    expect(labelProperty(s)).toBeUndefined();
+  });
+
+  test('a complex path is still a column — it just has no single predicate', () => {
+    const s = shape([
+      prop('city', {path: {seq: [{id: `${base}vocab#address`}, {id: `${base}vocab#city`}]} as never}),
+    ]);
+    expect(columnsFor(s, 'full').map((c) => c.key)).toEqual(['city']);
+  });
+
+  test('header prefers sh:name over the label key', () => {
+    const s = shape([prop('givenName', {name: 'First name'})]);
+    expect(columnsFor(s, 'full')[0].header).toBe('First name');
+  });
+});

package/src/columns.ts

@@ -0,0 +1,228 @@
+/**
+ * The table model: a shape in, ordered and filtered columns out.
+ *
+ * Pure and framework-free on purpose. Which columns a table shows, in what order, and
+ * which one carries the label is the part worth testing and the part that has to behave
+ * identically wherever the table renders. Keeping it out of the React layer means it can
+ * be exercised directly, and means a different renderer (a mobile list, a picker, a
+ * printed view) makes the same decisions.
+ *
+ * The rule throughout: **what the shape declares beats what the renderer guesses.**
+ * `linked_core:displayRank` orders, `linked_core:displayHidden` removes, `sh:order`
+ * breaks ties. The heuristics apply only where a shape declares nothing — which, until
+ * the display vocabulary existed, was everywhere.
+ */
+
+import type {
+  NodeShapeWire,
+  PropertyShapeWire,
+} from '@_linked/core/shapes/nodeShapeWire';
+
+/**
+ * Whether the table shows the columns it judges useful, or every column.
+ *
+ * Lives here rather than in a page. `InstanceOverview` and `ReactTable` both imported this
+ * type from `pages/InstanceOverviewPage` — organisms depending on a page, which is exactly
+ * backwards and would have blocked moving either of them.
+ */
+export type TableMode = 'auto' | 'full';
+
+/** How much room the caller has. A table shows more than a card; a cell shows one. */
+export type DisplayContext = 'cell' | 'card' | 'table' | 'full';
+
+const CONTEXT_LIMITS: Record<DisplayContext, number> = {
+  cell: 1,
+  card: 3,
+  table: 6,
+  full: Number.POSITIVE_INFINITY,
+};
+
+/** Predicates that conventionally carry a human label, best first. */
+const LABEL_PREDICATES = [
+  'http://www.w3.org/2000/01/rdf-schema#label',
+  'http://www.w3.org/2004/02/skos/core#prefLabel',
+  'http://schema.org/name',
+  'http://purl.org/dc/terms/title',
+  'http://purl.org/dc/elements/1.1/title',
+  'http://xmlns.com/foaf/0.1/name',
+];
+
+/** Names that read as an identity rather than an attribute. */
+const NAMEY = /(name|label|title|identifier|handle|slug|heading|caption)/i;
+
+/** Datatypes whose values are too long to sit in a table cell. */
+const LONG_TEXT = new Set([
+  'http://www.w3.org/1999/02/22-rdf-syntax-ns#HTML',
+  'http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral',
+]);
+
+export interface Column {
+  /** The property this column reads. */
+  property: PropertyShapeWire;
+  /** The key a row object is expected to carry — the property's label. */
+  key: string;
+  /** What to put in the header. */
+  header: string;
+  /** True for the column that best identifies the row. */
+  isLabel: boolean;
+}
+
+/** The predicate IRI of a simple path, or undefined for a complex one. */
+function predicateOf(property: PropertyShapeWire): string | undefined {
+  const path = property.path as unknown;
+  if (typeof path === 'string') return path;
+  if (path && typeof path === 'object' && 'id' in (path as {id?: string})) {
+    return (path as {id: string}).id;
+  }
+  return undefined; // sequence / alternative / inverse — not a single predicate
+}
+
+function localName(iri: string): string {
+  const cut = Math.max(iri.lastIndexOf('#'), iri.lastIndexOf('/'));
+  return cut >= 0 ? iri.slice(cut + 1) : iri;
+}
+
+/**
+ * Whether a property can be shown at a given context.
+ *
+ * What fits depends on how much room there is, and an earlier version of this got that
+ * wrong: it applied the narrowest rule everywhere, so wiring it into a table silently
+ * deleted every relation, multi-valued and long-text column. A cell really can only hold
+ * one short scalar. A table can hold a badge for a related node, and a row of them.
+ */
+function fitsContext(
+  property: PropertyShapeWire,
+  context: DisplayContext,
+): boolean {
+  const isRelation = !!(property.valueShape || property.class);
+  const isMultiValued = property.maxCount != null && property.maxCount !== 1;
+  const isLongText = !!property.datatype && LONG_TEXT.has(property.datatype.id);
+
+  switch (context) {
+    case 'cell':
+      // One value, rendered inline. A relation would need a badge and a long text would
+      // need truncation; neither belongs in a cell that stands in for the whole instance.
+      return !isRelation && !isMultiValued && !isLongText;
+    case 'card':
+      // Room for a few values including a related node, but still not a wall of text.
+      return !isLongText;
+    case 'table':
+      // A table renders relations as badges and multi-values as a row of them. Long text
+      // is the one thing that breaks a row's height.
+      return !isLongText;
+    case 'full':
+      // A detail view shows everything the shape does not hide.
+      return true;
+  }
+}
+
+/**
+ * Sort key for an undeclared value. A finite sentinel rather than `Infinity`, because
+ * `Infinity - Infinity` is `NaN` and a comparator that returns NaN is undefined by spec —
+ * it happened to behave because V8 reads NaN as "equal".
+ */
+const UNDECLARED = Number.MAX_SAFE_INTEGER;
+
+const declaredRank = (p: PropertyShapeWire): number => p.displayRank ?? UNDECLARED;
+const declaredOrder = (p: PropertyShapeWire): number => p.order ?? UNDECLARED;
+
+/** Declared precedence: rank, then `sh:order`. Undeclared properties sort last. */
+function byDeclared(a: PropertyShapeWire, b: PropertyShapeWire): number {
+  return declaredRank(a) - declaredRank(b) || declaredOrder(a) - declaredOrder(b);
+}
+
+/**
+ * Heuristic score, used only where nothing is declared. Higher is more important.
+ *
+ * These weights are a guess dressed as a number, and they exist so a shape that says
+ * nothing still renders sensibly. A shape that declares `displayRank` never reaches here.
+ */
+function score(property: PropertyShapeWire): number {
+  let s = 0;
+  if ((property.minCount ?? 0) > 0) s += 100;
+  const name = `${property.label ?? ''} ${localName(predicateOf(property) ?? '')}`;
+  if (NAMEY.test(name)) s += 50;
+  if (/(type|description|date|email|url)/i.test(name)) s += 25;
+  if (property.datatype) s += 10;
+  return s;
+}
+
+/**
+ * Properties the shape does not hide, and that fit the given context.
+ *
+ * `displayHidden` is checked first and applies to every context: it is a statement about
+ * the property, not about how much room there is.
+ */
+export function displayableProperties(
+  shape: NodeShapeWire,
+  context: DisplayContext = 'table',
+): PropertyShapeWire[] {
+  return (shape.propertyShapes ?? []).filter(
+    (p) => p.displayHidden !== true && !!p.label && fitsContext(p, context),
+  );
+}
+
+/** True when any property on the shape declares a rank. */
+export function hasDeclaredRanks(shape: NodeShapeWire): boolean {
+  return (shape.propertyShapes ?? []).some((p) => p.displayRank != null);
+}
+
+/**
+ * The property that best identifies an instance of this shape.
+ *
+ * Declared rank first; then a conventional label predicate; then a name-ish literal.
+ * Undefined when the shape has nothing showable — the caller falls back to the IRI, which
+ * is a display decision and not this function's to make.
+ */
+export function labelProperty(
+  shape: NodeShapeWire,
+  context: DisplayContext = 'cell',
+): PropertyShapeWire | undefined {
+  // The label stands in for the whole instance, so it is held to the CELL rule even when
+  // the surrounding table is wider — a relation or a blob does not identify a row.
+  const candidates = displayableProperties(shape, context);
+  if (candidates.length === 0) return undefined;
+
+  if (hasDeclaredRanks(shape)) {
+    const ranked = candidates
+      .filter((p) => p.displayRank != null)
+      .sort(byDeclared);
+    if (ranked.length) return ranked[0];
+  }
+
+  for (const predicate of LABEL_PREDICATES) {
+    const match = candidates.find((p) => predicateOf(p) === predicate);
+    if (match) return match;
+  }
+
+  return candidates.find((p) =>
+    NAMEY.test(`${p.label} ${localName(predicateOf(p) ?? '')}`),
+  );
+}
+
+/**
+ * Columns for a shape at a given context, label first.
+ *
+ * `limit` overrides the context's own limit for a caller that knows its space better.
+ */
+export function columnsFor(
+  shape: NodeShapeWire,
+  context: DisplayContext = 'table',
+  limit?: number,
+): Column[] {
+  const label = labelProperty(shape);
+  const declared = hasDeclaredRanks(shape);
+
+  const rest = displayableProperties(shape, context).filter((p) => p !== label);
+  rest.sort(declared ? byDeclared : (a, b) => score(b) - score(a));
+
+  const ordered = label ? [label, ...rest] : rest;
+  const max = limit ?? CONTEXT_LIMITS[context];
+
+  return ordered.slice(0, max).map((property) => ({
+    property,
+    key: property.label,
+    header: property.name || property.label,
+    isLabel: property === label,
+  }));
+}