@_linked/shape-ui 2.0.0 → 2.3.0

package/src/components/forms.module.css

@@ -0,0 +1,96 @@
+/* ============================================================================
+   EditInstanceForms.module.css
+
+   Form layout for editing instance data.
+   Matches ViewInstance styling with card container.
+   Uses semantic tokens from theme.css.
+   ============================================================================ */
+
+/* === Container (Card) === */
+.container {
+  background: var(--surface-bg);
+  border: 1px solid var(--surface-border);
+  border-radius: var(--radius-box);
+  margin: var(--section-gap) 0;
+}
+
+/* === Rows Wrapper === */
+.rows {
+  padding: var(--surface-gap) var(--space-2xl) var(--space-lg) var(--space-2xl);
+}
+
+/* === Section Title === */
+.sectionTitle {
+  margin: 0;
+  padding: var(--surface-padding) var(--space-2xl) 0 var(--space-2xl);
+  font-size: var(--typography-small-size);
+  color: var(--forms-gray-500, var(--color-gray-500));
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+/* === Add Field Section === */
+.addFieldSection {
+  padding: var(--space-sm) 0;
+}
+
+/* === Save Error === */
+.saveError {
+  color: var(--intent-danger-text);
+  font-size: var(--typography-small-size);
+  margin: var(--space-sm) 0 0;
+}
+
+/* === Actions === */
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--surface-gap);
+  margin-top: var(--space-lg);
+}
+
+/* ============================================================================
+   Dark Mode
+   ============================================================================ */
+
+/* .container uses --card-bg / --card-border which auto-switch in dark mode */
+
+[data-theme='dark'] .sectionTitle {
+  color: var(--forms-gray-400, var(--color-gray-400));
+}
+
+/* ============================================================================
+   Mobile Responsive Styles
+   ============================================================================ */
+
+@media only screen and (max-width: 768px) {
+  .rows {
+    padding: var(--space-sm) var(--space-md);
+  }
+}
+
+@media only screen and (max-width: 480px) {
+  .container {
+    margin: var(--space-md) 0;
+    border-radius: var(--radius-field);
+  }
+
+  .rows {
+    padding: var(--space-xs) var(--space-sm);
+  }
+
+  .sectionTitle {
+    padding: var(--space-sm) var(--space-sm) 0 var(--space-sm);
+    font-size: 0.6875rem;
+  }
+
+  .actions {
+    flex-direction: column-reverse;
+    gap: var(--space-sm);
+  }
+
+  .actions button {
+    width: 100%;
+  }
+}

package/src/host.ts

@@ -0,0 +1,226 @@
+/**
+ * What a host application supplies to the data manager.
+ *
+ * The point of this contract is what it does NOT contain: no project id, no branch, no
+ * store, no dataset name. Routing is decided below the component by `LinkedStorage` —
+ * `AppDataRouter` inside Create Now, the app's own default dataset in a standalone or
+ * Capacitor build — so the component issues a Linked Query and never names a project.
+ * Everything here is genuinely host-specific: where IRIs are minted, how the catalog is
+ * found, and where a click should go.
+ */
+
+import type {NodeShapeWire} from '@_linked/core/shapes/nodeShapeWire';
+import type {ReactNode} from 'react';
+
+/** Where a host sends the viewer when they act on a row. */
+export interface DataManagerNavigation {
+  toInstance(shapeIri: string, instanceId: string): void;
+  toEdit(shapeIri: string, instanceId: string): void;
+  toAdd(shapeIri: string): void;
+}
+
+/**
+ * "Pick mode" — the flow where a form asks the user to choose a related instance and
+ * returns with it. Optional because it is a Create Now studio affordance; a standalone
+ * app that has no such flow simply omits it, rather than being asked to stub it.
+ */
+/** What a field needs the host to open a picker for. */
+export interface PickRequest {
+  /** The shape whose instances the viewer should choose from. */
+  shapeIri: string;
+  /** The field asking, so the host can route the answer back to it. */
+  propertyLabel: string;
+  /** The shape being edited — the same field label can exist on more than one. */
+  sourceShapeIri?: string;
+  minCount?: number;
+  maxCount?: number;
+  /** Already-chosen values, so the picker can show them as selected. */
+  alreadySelected?: InstanceSuggestion[];
+  /**
+   * An opaque token the host must carry across the round trip and hand back on return.
+   *
+   * A field with unsaved work flushes it before the viewer leaves, and that flush yields
+   * an identifier — Create Now's draft id — without which the half-filled form is lost on
+   * the way back. The field cannot store it itself; it is about to unmount. It is opaque
+   * here on purpose: how a host preserves it is its own business (Create Now puts it in
+   * the return URL), and a host with no navigation to survive can ignore it.
+   */
+  resumeToken?: string;
+}
+
+export interface DataManagerPicking {
+  /**
+   * A field is asking the viewer to choose. How that is presented is entirely the host's
+   * call — Create Now navigates to the overview in pick mode, a mobile app would open a
+   * sheet — which is why this is a request rather than a URL.
+   *
+   * A host that omits `picking` gets a picker with no "browse all" affordance rather than
+   * a broken one; the inline search still works.
+   */
+  open(request: PickRequest): void;
+
+  /**
+   * The viewer completed a choice.
+   *
+   * Called ONCE per completed choice with everything chosen, not once per instance —
+   * a multi-pick host has to write all the values and then return, and per-instance calls
+   * made it navigate away on the first one.
+   *
+   * The full suggestion is passed, not just the id, because the host generally has to
+   * store something displayable straight away: the field that opened the picker renders
+   * a chip before anything re-reads the instance. Passing an id alone forced the host to
+   * look the label back up, which is a read it should not need.
+   */
+  select(instances: InstanceSuggestion[]): void;
+
+  /**
+   * The return leg: values the viewer picked for this field while it was away.
+   *
+   * A field that sends the viewer elsewhere to choose is unmounted by the time they do,
+   * so the answer cannot be handed back through a callback — the field has to ask for it
+   * when it mounts again. Which is why `open` and `select` alone were not enough: the
+   * component was reading Create Now's sessionStorage directly to close the loop.
+   *
+   * Returns only what belongs to THIS field: several relation fields can be on one form,
+   * and the picked values must not land in the wrong one. Returns null when there is
+   * nothing waiting, which is the normal case on almost every mount.
+   *
+   * The host consumes the result. Note that under React Strict Mode a field mounts,
+   * unmounts and mounts again, so a host that clears synchronously will lose the value
+   * on the second mount — clear on a later tick.
+   */
+  takeResult(field: {
+    propertyLabel: string;
+    sourceShapeIri?: string;
+  }): InstanceSuggestion[] | null;
+}
+
+/** One candidate for a relation field. */
+export interface InstanceSuggestion {
+  id: string;
+  label: string;
+  image?: string;
+}
+
+export interface SearchInstancesOptions {
+  /** Free text; empty means "browse". */
+  query?: string;
+  limit?: number;
+  offset?: number;
+  /** Restrict to these ids — used when another field's value narrows the choices. */
+  narrowedIds?: string[] | null;
+}
+
+export interface DataManagerHost {
+  /**
+   * Base IRI for minting new instance IRIs.
+   *
+   * In Create Now this is the project's `dataRoot` — the ONE value in the catalog path
+   * that comes from cn-main rather than the app's own dataset. A standalone app knows its
+   * own domain and passes it from config, which is why this is a plain value here and not
+   * a lookup.
+   */
+  dataRoot?: string;
+
+  /**
+   * The metadata for ONE shape, by IRI.
+   *
+   * The only required member, and deliberately the smallest one that works. It used to ask
+   * for the whole catalog, which read as though a consumer needed a catalogue query before
+   * they could render anything — and that is not what the components do with it. There are
+   * exactly two uses: resolving the shape a relation field is searching, and resolving the
+   * shape a form is writing to. Both want one shape.
+   *
+   * So an app that composes a page for `Contact` returns its `Contact` shape from a constant
+   * and is done. An app that does have a catalog answers from it. Neither is asked to build
+   * a shape browser in order to render one table.
+   *
+   * Return `undefined` for an unknown IRI: a search then yields nothing rather than
+   * guessing, and a write is refused rather than putting untyped triples in the graph.
+   */
+  resolveShape(shapeIri: string): Promise<NodeShapeWire | undefined>;
+
+  /**
+   * The whole catalog, when the host happens to have one.
+   *
+   * Optional, and only a convenience: supplying it means `resolveShape` can be derived, so a
+   * host with a catalog need not write both.
+   */
+  resolveCatalog?(): Promise<Record<string, NodeShapeWire>>;
+
+  /**
+   * Find instances of a shape, for a relation field's picker.
+   *
+   * A host concern because *how* you search is host-specific: Create Now asks its backend
+   * on behalf of a project, a standalone app queries its own dataset. What the picker needs
+   * back is the same either way — id, a human label, optionally an image.
+   */
+  searchInstances?(
+    shapeIri: string,
+    options?: SearchInstancesOptions,
+  ): Promise<{results: InstanceSuggestion[]; hasMore: boolean}>;
+
+  /**
+   * Render a form for creating a related instance inline, without leaving the field.
+   *
+   * A render slot rather than a component reference on purpose. The relation picker used to
+   * `import AddInstanceForms` directly — a molecule importing an organism, which is a cycle
+   * and also the single thing that made the picker unextractable. The host decides what
+   * "create one of these" looks like; the picker only decides when to ask.
+   */
+  inlineCreate?(args: {
+    shapeIri: string;
+    onCreated: (created: InstanceSuggestion) => void;
+    onCancel: () => void;
+  }): ReactNode;
+
+  /**
+   * Read one instance's values.
+   *
+   * Used by the form's dependency cascade, which needs a parent instance's values to narrow
+   * a child field's choices. On the host because the read is host-specific; the cascade
+   * logic is not.
+   */
+  readInstance?(
+    shapeIri: string,
+    instanceId: string,
+  ): Promise<{rows: Record<string, unknown>[]}>;
+
+  navigate?: DataManagerNavigation;
+  picking?: DataManagerPicking;
+
+  /**
+   * Create an instance and return its IRI.
+   *
+   * Optional, and filled in from the DSL when absent — like `searchInstances`, and for the
+   * same reason: a form that cannot save unless the host wrote a create by hand is not
+   * "works standalone". Create Now overrides it only because its create also has to write
+   * a draft and record a projection edit, neither of which is a write concern.
+   */
+  createInstance?(
+    shapeIri: string,
+    values: Record<string, unknown>,
+  ): Promise<{id: string}>;
+
+  /** Update an instance. Optional, and filled in from the DSL when absent. */
+  updateInstance?(
+    shapeIri: string,
+    instanceId: string,
+    values: Record<string, unknown>,
+  ): Promise<void>;
+}
+
+/**
+ * A host with nothing wired up: catalog is empty, navigation is a no-op.
+ *
+ * For tests and for a first render before the real host exists. Deliberately silent
+ * rather than throwing — a missing host should render an empty table, not break the page
+ * that embedded it.
+ */
+export function nullHost(): DataManagerHost {
+  return {
+    async resolveShape() {
+      return undefined;
+    },
+  };
+}

package/src/hostContext.tsx

@@ -0,0 +1,114 @@
+/**
+ * The host, supplied by context rather than threaded as props.
+ *
+ * The components that need the host are three levels down — a form renders a field, which
+ * renders a value editor, which renders the relation picker — and the picker is the one
+ * that needs to search, navigate and offer inline creation. Passing four callbacks through
+ * every intermediate component would put host concerns in the signature of components that
+ * have no interest in them.
+ *
+ * So: one provider at the top, `useDataManagerHost()` where it is needed. The default is
+ * `nullHost()`, which does nothing rather than throwing — a component rendered without a
+ * provider should show an empty picker, not break the page that embedded it.
+ */
+
+import {createContext, createElement, useContext, useMemo, type ReactNode} from 'react';
+import {nullHost, type DataManagerHost} from './host.js';
+import {registerRuntimeShapes} from '@_linked/core/shapes/registerRuntimeShape';
+import {narrowSuggestions, searchInstancesWithDsl} from './search.js';
+import {createInstanceWithDsl, updateInstanceWithDsl} from './write.js';
+
+const HostContext = createContext<DataManagerHost>(nullHost());
+
+export interface DataManagerHostProviderProps {
+  host: DataManagerHost;
+  children?: ReactNode;
+}
+
+export function DataManagerHostProvider({
+  host,
+  children,
+}: DataManagerHostProviderProps) {
+  return createElement(HostContext.Provider, {value: host}, children);
+}
+
+/**
+ * The host for the surrounding provider, with the defaults filled in.
+ *
+ * `searchInstances`, `createInstance` and `updateInstance` are supplied from the DSL when
+ * the host does not provide them, so reading, searching and saving all work with no host
+ * wiring at all. Callers therefore never branch on whether a method exists — which they
+ * previously had to, and which meant a host that forgot one rendered a silently empty
+ * picker or a form whose save button did nothing.
+ *
+ * Read and write are filled in from the same place on purpose. They are routed by
+ * `LinkedStorage` as a pair, and a read routed one way with a write routed another is how
+ * a form saves into a dataset the table is not looking at.
+ */
+export function useDataManagerHost(): DataManagerHost {
+  const host = useContext(HostContext);
+
+  return useMemo<DataManagerHost>(() => {
+    const filled: DataManagerHost = {...host};
+
+    // Resolve one shape, and register it on the way through.
+    //
+    // `SelectBuilder.from(shapeIri)` resolves the IRI against core's shape registry, so a
+    // shape that was never registered produces an EMPTY result rather than an error — a table
+    // that silently shows nothing, indistinguishable from a shape with no instances. Asking
+    // the host to remember `registerRuntimeShapes` would make that the first thing every
+    // consumer gets wrong, so it happens here. Registration is idempotent and never shadows a
+    // compiled class.
+    //
+    // A host that supplied only `resolveCatalog` is served from it, so having a catalog does
+    // not mean writing the single-shape lookup as well.
+    const resolveShape = async (shapeIri: string) => {
+      const shape = host.resolveShape
+        ? await host.resolveShape(shapeIri)
+        : (await host.resolveCatalog?.())?.[shapeIri];
+      if (shape) registerRuntimeShapes([shape]);
+      return shape;
+    };
+    filled.resolveShape = resolveShape;
+
+    /** The shape, or a thrown error naming the IRI — a write must not guess. */
+    const requireShape = async (shapeIri: string) => {
+      const shape = await resolveShape(shapeIri);
+      if (!shape) {
+        throw new Error(
+          `Cannot write to ${shapeIri}: it is not in the catalog this host resolved. ` +
+            'A write against an unknown shape would put untyped triples in the graph.',
+        );
+      }
+      return shape;
+    };
+
+    if (!filled.searchInstances) {
+      filled.searchInstances = async (shapeIri, options) => {
+        const shape = await resolveShape(shapeIri);
+        // No shape means no label property and no idea what to project. An empty result is
+        // the honest answer; guessing a projection would produce a wrong query.
+        if (!shape) return {results: [], hasMore: false};
+        const found = await searchInstancesWithDsl(shape, options);
+        return {
+          ...found,
+          results: narrowSuggestions(found.results, options?.narrowedIds),
+        };
+      };
+    }
+
+    if (!filled.createInstance) {
+      filled.createInstance = async (shapeIri, values) =>
+        createInstanceWithDsl(await requireShape(shapeIri), values, {
+          dataRoot: host.dataRoot,
+        });
+    }
+
+    if (!filled.updateInstance) {
+      filled.updateInstance = async (shapeIri, instanceId, values) =>
+        updateInstanceWithDsl(await requireShape(shapeIri), instanceId, values);
+    }
+
+    return filled;
+  }, [host]);
+}

package/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * `@_linked/shape-ui` — UI driven by a shape.
+ *
+ * Two halves that grew separately and belong together.
+ *
+ * The **editors** take a shape and a property and render one control — a text field, a select,
+ * a date picker. Import them by path: `@_linked/shape-ui/components/TextfieldEditor`.
+ *
+ * The **surfaces** are what you build out of those: a table over any shape's instances, a form
+ * derived from its property list, a read-only view, a relation picker, and the shape domain
+ * underneath — column derivation, property visibility, validation, and the read and write paths
+ * through the Linked Query DSL.
+ *
+ * The surfaces arrived from `@create-now/data-manager`, where they were private on the
+ * assumption that shape-driven CRUD was a product. It is not: it renders any shape, knows
+ * nothing about projects, and is worth nothing without shapes to render. The product is the
+ * studio that authors them. See arch-03 §UI package layering.
+ *
+ * `./package.js` is imported below, as in every other `@_linked/*` package, so this package
+ * registers itself — the house pattern, nothing special here. It briefly had to be omitted:
+ * it triggered "Class extends value undefined is not a constructor or null" from inside a
+ * query. That was never this package's fault — it was a live-binding bug in core's
+ * `ShapeClass`, which captured `Shape` by named import before `Shape.js` had finished
+ * evaluating, so the runtime subclass extended `undefined`. Fixed in `@_linked/core` 2.18.1
+ * (linked-cm/core#220), which is why this package depends on `^2.18.1`.
+ *
+ * The empty ontology this package scaffolded from the template is gone: one export, no terms,
+ * and a namespace on a domain we no longer use. Nothing referenced it.
+ */
+
+// Registers this package with the linked package system. The only side effect in this barrel.
+import './package.js';
+
+
+export type {
+  DataManagerHost,
+  DataManagerNavigation,
+  DataManagerPicking,
+  PickRequest,
+  InstanceSuggestion,
+  SearchInstancesOptions,
+} from './host.js';
+export {nullHost} from './host.js';
+
+export type {DataManagerHostProviderProps} from './hostContext.js';
+export {DataManagerHostProvider, useDataManagerHost} from './hostContext.js';
+
+export type {InstanceQuery, InstanceRows} from './read.js';
+export {selectInstance, selectInstances} from './read.js';
+
+export type {InstanceValues} from './write.js';
+export {
+  createInstanceWithDsl,
+  mintInstanceIri,
+  updateInstanceWithDsl,
+} from './write.js';
+
+export type {Column, DisplayContext, TableMode} from './columns.js';
+export {
+  columnsFor,
+  displayableProperties,
+  hasDeclaredRanks,
+  labelProperty,
+} from './columns.js';
+
+export {narrowSuggestions, searchInstancesWithDsl} from './search.js';
+
+// ─── Components ──────────────────────────────────────────────────────────────
+//
+// The shape-driven CRUD surfaces. Each one takes shape metadata and instance data and asks
+// the host for anything that is specific to the application around it — where a click leads,
+// where an IRI is minted, how a picker is opened.
+export {default as InstanceOverview} from './components/InstanceOverview.js';
+export type {BatchResult} from './components/InstanceOverview.js';
+export {default as ReactTable} from './components/ReactTable.js';
+export type {ReactTableProps} from './components/ReactTable.js';
+export {InstanceView} from './components/InstanceView.js';
+export {default as AddInstanceForms} from './components/AddInstanceForms.js';
+export {default as EditInstanceForms} from './components/EditInstanceForms.js';
+export {InstanceDeletionDialog} from './components/InstanceDeletionDialog.js';
+export {default as BatchEditDrawer} from './components/BatchEditDrawer.js';
+export {default as CustomMultiSelect} from './components/CustomMultiSelect.js';
+export {DynamicForm} from './components/DynamicFormField.js';
+export {FormField} from './components/FormField.js';
+export {default as NodeValuesEditor} from './components/NodeValuesEditor.js';
+export {NodeBadge} from './components/NodeBadge.js';
+export {FilterBadge} from './components/FilterBadge.js';
+
+// ─── Shape domain ────────────────────────────────────────────────────────────
+export * from './shape/contracts.js';
+export * from './shape/naming.js';
+export * from './shape/nodeDisplay.js';
+export * from './shape/propertyVisibility.js';

package/src/package.ts

@@ -0,0 +1,21 @@
+import {
+  getPackageShape,
+  linkedOntology,
+  linkedShape,
+  linkedUtil,
+  packageExports,
+  registerPackageExport,
+  registerPackageModule,
+} from '@_linked/core/package';
+
+export const { packageName } = { packageName: '@_linked/ui' };
+
+export {
+  getPackageShape,
+  linkedOntology,
+  linkedShape,
+  linkedUtil,
+  packageExports,
+  registerPackageExport,
+  registerPackageModule,
+};