@phis/ui 0.1.0 → 0.2.1

package/types/state-machine.d.ts

@@ -0,0 +1,229 @@
+import { type PhiSignalValueSchema } from "./signals";
+import type { PhiRuntimeConditionExpression } from "./runtime-condition";
+import type { PhiRuntimeModuleId } from "./cms-module-descriptors";
+/**
+ * A named description of the states one piece of work can be in, and how it moves between them.
+ *
+ * It lives here and not in `@phis/contracts` because phi-server never sees one. What that package holds
+ * is what phi-server reads: the signal vocabulary it validates on stored wiring, the user-state shapes it
+ * checks a write against. A machine definition belongs to a Module the way a Controller descriptor does,
+ * and the guards below are `PhiRuntimeConditionExpression`, which is itself stored on CMS nodes and read
+ * by nobody on the server side. Moving this across would drag that whole vocabulary to a party with no
+ * use for it. ([design/STATE_MACHINES.md](../design/STATE_MACHINES.md), which is still a design: this is
+ * the grammar and the binding runs it, but most of what that document describes is unbuilt.)
+ *
+ * Nothing here is executable and nothing here is a reference to something executable. A definition is
+ * serializable on the same terms as a Form descriptor: no callbacks, no element references, no
+ * selectors, no credentials, and no route targets. The design also gives a transition *effects* -- a
+ * signal to raise, a reader to call, a Page to forward to, each named rather than carried. They are not
+ * here, because the one machine that exists does not need them: its answer arrives on the same signal
+ * that raises the event, so a `read` would buy a second request for something already in hand. A
+ * machine whose outcome arrives separately is what would bring them back.
+ */
+/**
+ * Who decides what state the machine is in.
+ *
+ * This is the first field of a definition rather than an implementation detail, because it is the field
+ * that makes a whole class of mistake unavailable. Under `server` there is no local transition function
+ * to write, so a third party structurally cannot rebuild a security state machine in the browser -- which
+ * is what `phis-server` AUTHENTICATION.md §9 forbids in prose.
+ *
+ * A machine never mixes the two. Work that is partly server-owned -- a checkout whose payment step is
+ * settled elsewhere -- is two machines that coordinate, not one machine that is half of each.
+ */
+export declare const PHI_STATE_MACHINE_AUTHORITIES: readonly ["server", "client"];
+export type PhiStateMachineAuthority = (typeof PHI_STATE_MACHINE_AUTHORITIES)[number];
+/**
+ * Where the position is kept, and how long it survives.
+ *
+ * A machine's lifetime is its host's lifetime, and how long that is depends on which host mounted the
+ * Controller -- Layout-hosted survives a navigation within its Area, Page-hosted does not
+ * ([MODULES.md](../MODULES.md)). A machine that must outlast its host says so here rather than by
+ * being registered in the luckier tree.
+ *
+ * - `none` -- gone on unmount, which is the honest answer for most of them.
+ * - `query` -- validated query parameters. What the reset-password and confirm flows use today, what
+ *   makes an emailed link resumable, and what costs nothing because it is in the address bar already.
+ * - `server` -- the authoritative store behind a `server` authority machine. The binding holds a copy
+ *   and re-reads it; it never writes it.
+ * - `profile` -- the account-bound store ([design/USER_STATE.md](../design/USER_STATE.md)), under the
+ *   key `<ownerModuleId>/<machineKey>`. Only for a signed-in viewer, never readable on Public, one
+ *   round trip per checkpoint and one request to resume. A machine that needs every step to survive a
+ *   reload wants `query` instead.
+ *
+ * `localStorage`, `sessionStorage`, a cookie invented for the purpose and a module global are not on
+ * this list and are not alternatives to it. The Form draft in `sessionStorage` stays what it is: typed
+ * input somebody has not sent, not a position in a flow.
+ */
+export declare const PHI_STATE_MACHINE_PERSISTENCE_TARGETS: readonly ["none", "query", "server", "profile"];
+export type PhiStateMachinePersistence = (typeof PHI_STATE_MACHINE_PERSISTENCE_TARGETS)[number];
+/**
+ * Which machine, named the way a route names a Page.
+ *
+ * `(ownerModuleId, machineKey)`, resolved through the Modules this Area runs -- never a
+ * `controller:` address written out. [THIRD_PARTY_MODULES.md](../THIRD_PARTY_MODULES.md) forbids the
+ * analogue for routes ("Your own path must not appear anywhere in your Module"), and the reason carries
+ * over unchanged: a written-out address breaks quietly the moment the instance is named differently or
+ * the owning Module is not active in that Area.
+ *
+ * The owner is a Module id and not a package name, for the reason the user-state key grammar gives: a
+ * package may carry two Modules and a Site may run one of them.
+ */
+export type PhiStateMachineReference = {
+    readonly ownerModuleId: PhiRuntimeModuleId;
+    readonly machineKey: string;
+};
+/**
+ * One state, and the two things it may say about itself.
+ *
+ * A state is a name first. `statements` is what outside readers see (below); `capability` is what the
+ * state needs in order to be shown at all, in the vocabulary `capabilitiesByArea` declares. Naming it
+ * here is what gave that vocabulary a reader: a host asks its Area's provider whether it offers what
+ * the state needs, and a state nobody here can present says so rather than leaving a visitor in front
+ * of an empty step.
+ *
+ * There is deliberately no `terminal` flag. A state with no transition out of it is terminal by being
+ * one, and a second spelling of that fact is a second thing to keep true.
+ */
+export type PhiStateMachineState = {
+    /** Which of the definition's published statements are true here. Absent means none of them are. */
+    readonly statements?: readonly string[];
+    /** The presentation capability this state needs a provider for. */
+    readonly capability?: string;
+};
+/**
+ * `(from, event) -> to`, optionally guarded.
+ *
+ * Keyed flat by transition key rather than nested under `from` and then `event`, because nesting makes
+ * the guarded alternative inexpressible -- one event, two targets, decided by a condition. Auth does not
+ * need it and the first non-trivial client machine probably will. What the nesting would have enforced
+ * is checked instead, by `collectPhiStateMachineDefinitionErrors`.
+ *
+ * A guard is a `PhiRuntimeConditionExpression`, so a guard and a `visibleWhen` are the same language,
+ * evaluated the same way, against the same sources. Nobody has to learn a second one.
+ */
+export type PhiStateMachineTransition = {
+    readonly from: string;
+    readonly event: string;
+    readonly to: string;
+    readonly when?: PhiRuntimeConditionExpression;
+};
+type PhiStateMachineDefinitionBase = {
+    readonly machineKey: string;
+    /**
+     * The identity of persisted state, and nothing else.
+     *
+     * Changing it deliberately makes a different machine: state recorded under an older version is
+     * discarded, never migrated. It is not a compatibility promise -- pre-v1 an ABI break is allowed even
+     * where a third party reads it, and that package is rebuilt. So there is no version tolerance to
+     * negotiate and a reader declares no version it was written against.
+     *
+     * A machine that must keep history across versions records it as domain data. History is not position.
+     */
+    readonly version: number;
+    readonly persistence: PhiStateMachinePersistence;
+    readonly initial: string;
+    readonly states: Readonly<Record<string, PhiStateMachineState>>;
+    readonly transitions: Readonly<Record<string, PhiStateMachineTransition>>;
+    /**
+     * The facts this machine publishes about itself, which is the whole of what an outside reader sees.
+     *
+     * State keys stay internal. A reader asking about them would be guessing at somebody else's field
+     * names -- which is what a `controller` condition does today, reading `permissions.readOnly` out of a
+     * `Record<string, unknown>`. The distinction already exists among the condition sources: `feature` is
+     * what a Module publishes deliberately under a name it keeps, `controller` is whatever somebody
+     * happened to report. A machine's published surface is its `feature`.
+     *
+     * The closed list is what makes it survive a new state. Because a state names the statements true in
+     * it, a state added later publishes none of them until its author says otherwise -- so a reader
+     * asking "is this complete" gets `false` from a state nobody told it about, rather than a negation
+     * over an open set silently becoming wrong. `noStepRunning()` in the login preset is that negation
+     * today, and it is why this is not optional.
+     */
+    readonly statements: readonly string[];
+    /**
+     * The shape of the `data` a snapshot carries -- not of the snapshot itself.
+     *
+     * The envelope is identical for every machine: reference, version, state key, statements. What
+     * differs is what a state hangs off it, and that is the part a reader has to know in advance and a
+     * third party or phi-server can check. The `<package>/signals/<key>` grammar because a snapshot
+     * travels as a signal value, and because the user-state `value` shape asks for a schema of exactly
+     * that form -- so a `profile` machine names this once and both hold it to it.
+     *
+     * Required even from a machine that carries no data yet. One that cannot name the shape of what it
+     * publishes has not finished deciding what it publishes.
+     */
+    readonly snapshotSchema: PhiSignalValueSchema;
+    /**
+     * Which events this machine accepts from outside its owning Module. None unless it says so.
+     *
+     * Reading is one thing and raising an event in somebody else's machine is another. Server authority
+     * softens this only halfway: Core still decides the outcome, but a foreign `enroll` is still an
+     * interference.
+     */
+    readonly acceptsExternalEvents?: readonly string[];
+};
+/**
+ * A machine definition, with `authority` deciding what else it must carry.
+ *
+ * Under `server` the `reader` is required by the type rather than by a rule somebody has to remember:
+ * a projection whose authoritative state cannot be re-read is not a projection, it is a guess that
+ * survives until the first reload. The reader is a name the host resolves, on the same terms as a Form
+ * handler key -- the definition stays serializable.
+ */
+export type PhiStateMachineDefinition = (PhiStateMachineDefinitionBase & {
+    readonly authority: "server";
+    readonly reader: string;
+}) | (PhiStateMachineDefinitionBase & {
+    readonly authority: "client";
+});
+/**
+ * What the machine is doing, as anybody reading it sees it.
+ *
+ * Readable on demand and not only observable as an event, which is the gap the signal bus leaves: it
+ * holds an addressed signal for a receiver that has not mounted, but nothing teaches a late receiver a
+ * value it already missed. A mode delivered only as an event has to be repeated on every registration;
+ * a snapshot is asked for.
+ *
+ * `statements` is resolved to every published name with a boolean, not just the true ones, so a reader
+ * can tell "false" from "this machine does not publish that at all".
+ */
+export type PhiStateMachineSnapshot = {
+    readonly machine: PhiStateMachineReference;
+    readonly version: number;
+    readonly state: string;
+    readonly statements: Readonly<Record<string, boolean>>;
+    readonly data?: Readonly<Record<string, unknown>>;
+};
+/**
+ * A persisted position: where it was, and which machine it belonged to.
+ *
+ * Stored under `query` or `profile`, and deliberately nothing more than this. Discarding on a version
+ * mismatch is what keeps an old position from being read as a current one -- and under `profile`
+ * discarding means clearing the key, because that store treats an absent key and a falsy one as
+ * different answers.
+ */
+export type PhiStateMachineCheckpoint = {
+    readonly version: number;
+    readonly state: string;
+};
+export declare function isPhiStateMachineAuthority(value: unknown): value is PhiStateMachineAuthority;
+export declare function isPhiStateMachinePersistence(value: unknown): value is PhiStateMachinePersistence;
+/**
+ * The user-state key a `profile` machine checkpoints under.
+ *
+ * Derived rather than declared, because the two parts are already there and a second declaration is a
+ * second thing that can disagree. It also lands the key where the store's authorization expects it: the
+ * prefix is the owning Module's id, which is the whole of what phi-server checks.
+ */
+export declare function createPhiStateMachineUserStateKey(reference: PhiStateMachineReference): `${string}/${string}/${string}`;
+/**
+ * Every error a definition can carry, collected rather than thrown one at a time.
+ *
+ * Collected because a Module author fixing one definition wants the whole list, the way
+ * `collectCmsSignalRouteErrors` gives phi-server the whole list of a wiring's faults. The determinism
+ * rules are the substance here: they are what the flat transition shape gave up structural enforcement
+ * of, and checking them is the price of the guarded alternative being expressible at all.
+ */
+export declare function collectPhiStateMachineDefinitionErrors(definition: PhiStateMachineDefinition): string[];
+export {};

package/types/state-machine.js

@@ -0,0 +1,161 @@
+import { isPhiSignalValueSchemaShape } from "./signals";
+/**
+ * A named description of the states one piece of work can be in, and how it moves between them.
+ *
+ * It lives here and not in `@phis/contracts` because phi-server never sees one. What that package holds
+ * is what phi-server reads: the signal vocabulary it validates on stored wiring, the user-state shapes it
+ * checks a write against. A machine definition belongs to a Module the way a Controller descriptor does,
+ * and the guards below are `PhiRuntimeConditionExpression`, which is itself stored on CMS nodes and read
+ * by nobody on the server side. Moving this across would drag that whole vocabulary to a party with no
+ * use for it. ([design/STATE_MACHINES.md](../design/STATE_MACHINES.md), which is still a design: this is
+ * the grammar and the binding runs it, but most of what that document describes is unbuilt.)
+ *
+ * Nothing here is executable and nothing here is a reference to something executable. A definition is
+ * serializable on the same terms as a Form descriptor: no callbacks, no element references, no
+ * selectors, no credentials, and no route targets. The design also gives a transition *effects* -- a
+ * signal to raise, a reader to call, a Page to forward to, each named rather than carried. They are not
+ * here, because the one machine that exists does not need them: its answer arrives on the same signal
+ * that raises the event, so a `read` would buy a second request for something already in hand. A
+ * machine whose outcome arrives separately is what would bring them back.
+ */
+/**
+ * Who decides what state the machine is in.
+ *
+ * This is the first field of a definition rather than an implementation detail, because it is the field
+ * that makes a whole class of mistake unavailable. Under `server` there is no local transition function
+ * to write, so a third party structurally cannot rebuild a security state machine in the browser -- which
+ * is what `phis-server` AUTHENTICATION.md §9 forbids in prose.
+ *
+ * A machine never mixes the two. Work that is partly server-owned -- a checkout whose payment step is
+ * settled elsewhere -- is two machines that coordinate, not one machine that is half of each.
+ */
+export const PHI_STATE_MACHINE_AUTHORITIES = ["server", "client"];
+/**
+ * Where the position is kept, and how long it survives.
+ *
+ * A machine's lifetime is its host's lifetime, and how long that is depends on which host mounted the
+ * Controller -- Layout-hosted survives a navigation within its Area, Page-hosted does not
+ * ([MODULES.md](../MODULES.md)). A machine that must outlast its host says so here rather than by
+ * being registered in the luckier tree.
+ *
+ * - `none` -- gone on unmount, which is the honest answer for most of them.
+ * - `query` -- validated query parameters. What the reset-password and confirm flows use today, what
+ *   makes an emailed link resumable, and what costs nothing because it is in the address bar already.
+ * - `server` -- the authoritative store behind a `server` authority machine. The binding holds a copy
+ *   and re-reads it; it never writes it.
+ * - `profile` -- the account-bound store ([design/USER_STATE.md](../design/USER_STATE.md)), under the
+ *   key `<ownerModuleId>/<machineKey>`. Only for a signed-in viewer, never readable on Public, one
+ *   round trip per checkpoint and one request to resume. A machine that needs every step to survive a
+ *   reload wants `query` instead.
+ *
+ * `localStorage`, `sessionStorage`, a cookie invented for the purpose and a module global are not on
+ * this list and are not alternatives to it. The Form draft in `sessionStorage` stays what it is: typed
+ * input somebody has not sent, not a position in a flow.
+ */
+export const PHI_STATE_MACHINE_PERSISTENCE_TARGETS = ["none", "query", "server", "profile"];
+const PHI_STATE_MACHINE_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export function isPhiStateMachineAuthority(value) {
+    return typeof value === "string" &&
+        PHI_STATE_MACHINE_AUTHORITIES.includes(value);
+}
+export function isPhiStateMachinePersistence(value) {
+    return typeof value === "string" &&
+        PHI_STATE_MACHINE_PERSISTENCE_TARGETS.includes(value);
+}
+/**
+ * The user-state key a `profile` machine checkpoints under.
+ *
+ * Derived rather than declared, because the two parts are already there and a second declaration is a
+ * second thing that can disagree. It also lands the key where the store's authorization expects it: the
+ * prefix is the owning Module's id, which is the whole of what phi-server checks.
+ */
+export function createPhiStateMachineUserStateKey(reference) {
+    return `${reference.ownerModuleId}/${reference.machineKey}`;
+}
+/**
+ * Every error a definition can carry, collected rather than thrown one at a time.
+ *
+ * Collected because a Module author fixing one definition wants the whole list, the way
+ * `collectCmsSignalRouteErrors` gives phi-server the whole list of a wiring's faults. The determinism
+ * rules are the substance here: they are what the flat transition shape gave up structural enforcement
+ * of, and checking them is the price of the guarded alternative being expressible at all.
+ */
+export function collectPhiStateMachineDefinitionErrors(definition) {
+    const errors = [];
+    const label = definition.machineKey || "<unnamed machine>";
+    if (!PHI_STATE_MACHINE_KEY_PATTERN.test(definition.machineKey)) {
+        errors.push(`${label}: machineKey must be lower-case letters, digits and hyphens.`);
+    }
+    if (!Number.isSafeInteger(definition.version) || definition.version < 1) {
+        errors.push(`${label}: version must be a positive integer.`);
+    }
+    if (!isPhiSignalValueSchemaShape(definition.snapshotSchema)) {
+        errors.push(`${label}: snapshotSchema must be "<package>/signals/<key>".`);
+    }
+    if (definition.authority === "server" && !definition.reader.trim()) {
+        errors.push(`${label}: a "server" authority machine is a projection and needs a reader. ` +
+            "Without one it cannot re-read the state it is showing, which is the whole of what a projection is.");
+    }
+    const stateKeys = new Set(Object.keys(definition.states));
+    if (stateKeys.size === 0) {
+        errors.push(`${label}: a machine needs at least one state.`);
+    }
+    if (!stateKeys.has(definition.initial)) {
+        errors.push(`${label}: initial state "${definition.initial}" is not among the declared states.`);
+    }
+    const statements = new Set(definition.statements);
+    for (const [stateKey, state] of Object.entries(definition.states)) {
+        for (const statement of state.statements ?? []) {
+            if (!statements.has(statement)) {
+                errors.push(`${label}: state "${stateKey}" publishes "${statement}", which the machine does not declare.`);
+            }
+        }
+    }
+    /*
+     * Determinism, which the flat shape has to be told rather than shown.
+     *
+     * Two unguarded transitions out of the same `(from, event)` is a coin toss over which one a reader of
+     * the object happens to reach first -- position carries no meaning in these objects, so there is no
+     * "first" to appeal to. And a guarded set without an unguarded fallback is a dead end that looks like
+     * a transition: the event arrives, every guard refuses, and nothing happens for a reason nobody
+     * wrote down.
+     */
+    const unguarded = new Map();
+    const guarded = new Map();
+    const events = new Set();
+    for (const [transitionKey, transition] of Object.entries(definition.transitions)) {
+        events.add(transition.event);
+        if (!stateKeys.has(transition.from)) {
+            errors.push(`${label}: transition "${transitionKey}" leaves undeclared state "${transition.from}".`);
+        }
+        if (!stateKeys.has(transition.to)) {
+            errors.push(`${label}: transition "${transitionKey}" targets undeclared state "${transition.to}".`);
+        }
+        if (!transition.event.trim()) {
+            errors.push(`${label}: transition "${transitionKey}" has no event.`);
+        }
+        const pair = `${transition.from}|${transition.event}`;
+        const bucket = transition.when ? guarded : unguarded;
+        bucket.set(pair, (bucket.get(pair) ?? 0) + 1);
+    }
+    for (const [pair, count] of unguarded) {
+        if (count > 1) {
+            const [from, event] = pair.split("|");
+            errors.push(`${label}: "${event}" from "${from}" has ${count} unguarded transitions, so which one is taken ` +
+                "depends on object order, which carries no meaning here. Guard all but one.");
+        }
+    }
+    for (const pair of guarded.keys()) {
+        if (!unguarded.has(pair)) {
+            const [from, event] = pair.split("|");
+            errors.push(`${label}: "${event}" from "${from}" is guarded with no unguarded fallback, so a refusal by ` +
+                "every guard is a dead end. Declare the transition that is taken when none of them match.");
+        }
+    }
+    for (const event of definition.acceptsExternalEvents ?? []) {
+        if (!events.has(event)) {
+            errors.push(`${label}: "${event}" is accepted from outside but no transition responds to it.`);
+        }
+    }
+    return errors;
+}

package/types/table-signal-values.d.ts

@@ -0,0 +1,8 @@
+import type { PhiTableActionSignalValue, PhiTableBindingParamsSignalValue, PhiTableColumnOrderSignalValue, PhiTableExpansionSignalValue, PhiTableQueryValue, PhiTableRowIdentity, PhiTableSelectionSignalValue } from "./table-widget";
+export declare function readRowIdentities(value: unknown): PhiTableRowIdentity[] | undefined;
+export declare function isPhiTableQueryValue(value: unknown): value is PhiTableQueryValue;
+export declare function readPhiTableBindingParamsSignalValue(value: unknown): PhiTableBindingParamsSignalValue | null;
+export declare function readPhiTableSelectionSignalValue(value: unknown): PhiTableSelectionSignalValue | null;
+export declare function readPhiTableColumnOrderSignalValue(value: unknown): PhiTableColumnOrderSignalValue | null;
+export declare function readPhiTableExpansionSignalValue(value: unknown): PhiTableExpansionSignalValue | null;
+export declare function readPhiTableActionSignalValue(value: unknown): PhiTableActionSignalValue | null;

package/types/table-signal-values.js

@@ -0,0 +1,71 @@
+import { isPhiRecord } from "../helpers/is-record";
+/*
+ * What a Table says on its Signals, read by whoever listens: the Table itself, the record and form
+ * runtimes, Module Controllers, and the Overlay container, which opens on a Table action. The container is
+ * on every page, and the rest of the table contract -- provider results, field validators, config readers
+ * -- is not something a page without a Table should download, so the readers live apart from it.
+ */
+export function readRowIdentities(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.every((entry) => typeof entry === "string" || (typeof entry === "number" && Number.isFinite(entry)))
+        ? value
+        : undefined;
+}
+export function isPhiTableQueryValue(value) {
+    return value == null ||
+        typeof value === "string" ||
+        typeof value === "number" && Number.isFinite(value) ||
+        typeof value === "boolean" ||
+        Array.isArray(value) && value.every((entry) => typeof entry === "string" || typeof entry === "number" && Number.isFinite(entry));
+}
+export function readPhiTableBindingParamsSignalValue(value) {
+    if (!isPhiRecord(value) || !isPhiRecord(value.params) ||
+        Object.values(value.params).some((paramValue) => !isPhiTableQueryValue(paramValue))) {
+        return null;
+    }
+    return { params: value.params };
+}
+export function readPhiTableSelectionSignalValue(value) {
+    const selectedRowIdentities = isPhiRecord(value)
+        ? readRowIdentities(value.selectedRowIdentities)
+        : undefined;
+    return selectedRowIdentities ? { selectedRowIdentities } : null;
+}
+export function readPhiTableColumnOrderSignalValue(value) {
+    if (!isPhiRecord(value) || !Array.isArray(value.columnOrder) ||
+        !value.columnOrder.every((entry) => typeof entry === "string" && entry.trim().length > 0)) {
+        return null;
+    }
+    const columnOrder = value.columnOrder;
+    return new Set(columnOrder).size === columnOrder.length ? { columnOrder } : null;
+}
+export function readPhiTableExpansionSignalValue(value) {
+    const expandedRowIdentities = isPhiRecord(value)
+        ? readRowIdentities(value.expandedRowIdentities)
+        : undefined;
+    return expandedRowIdentities ? { expandedRowIdentities } : null;
+}
+export function readPhiTableActionSignalValue(value) {
+    if (!isPhiRecord(value) || typeof value.actionKey !== "string" || !value.actionKey.trim()) {
+        return null;
+    }
+    const selectedRowIdentities = readRowIdentities(value.selectedRowIdentities);
+    if (!selectedRowIdentities)
+        return null;
+    const rowIdentity = value.rowIdentity;
+    if (rowIdentity !== undefined && rowIdentity !== null &&
+        typeof rowIdentity !== "string" &&
+        (typeof rowIdentity !== "number" || !Number.isFinite(rowIdentity))) {
+        return null;
+    }
+    if (value.actionValue !== undefined && !isPhiTableQueryValue(value.actionValue)) {
+        return null;
+    }
+    return {
+        actionKey: value.actionKey.trim(),
+        rowIdentity: rowIdentity,
+        selectedRowIdentities,
+        actionValue: value.actionValue,
+    };
+}

package/types/table-widget.d.ts

@@ -1,8 +1,9 @@
+import type { PhiProviderResourceSource } from "./runtime-data-provider";
 import type { PhiControlPresentationConfig, PhiFeedbackLevel } from "./control";
 import type { PhiCssLength } from "./length";
 import type { PhiControlOption, PhiControlOptionsProviderConfig } from "../components/controls/phi-control-options";
 import type { PhiRuntimeDataProviderKey } from "./runtime-data-provider";
-import type { PhiSignalRouteSet } from "./signals";
+import type { PhiProviderDropMode, PhiProviderDropTargetCapability, PhiSignalRouteSet } from "./signals";
 import type { PhiRuntimeConditionExpression } from "./runtime-condition";
 export type PhiTableRowIdentity = string | number;
 export type PhiTableSortDirection = "ascending" | "descending";
@@ -44,6 +45,11 @@ export type PhiTableQuery = {
     filters?: Readonly<Record<string, PhiTableQueryValue>>;
     expandedRowIdentities?: readonly PhiTableRowIdentity[];
 };
+/**
+ * How a Provider value is drawn. Named rather than written into the column, because a record of the
+ * same rows draws the same values and must mean the same thing by `datetime` as the table does.
+ */
+export type PhiTableValueRenderer = "text" | "email" | "date" | "datetime" | "badge" | "tags" | "link" | "code" | "json" | "switch" | "checkbox" | "icon";
 export type PhiTableColumnDefinition = {
     key: string;
     title: string;
@@ -66,7 +72,13 @@ export type PhiTableColumnDefinition = {
      */
     titleIcon?: string;
     titleDisplay?: "icon-label" | "icon";
-    renderer?: "text" | "email" | "date" | "datetime" | "badge" | "tags" | "link" | "code" | "json" | "switch" | "checkbox" | "icon";
+    /**
+     * A hint on the heading, for a column whose title cannot say everything -- a switch whose effect
+     * needs a sentence. Shown as the description glyph beside the heading, with the text on hover and
+     * as its accessible name; the heading itself stays as short as the column is narrow.
+     */
+    description?: string;
+    renderer?: PhiTableValueRenderer;
     editor?: {
         control?: PhiTableColumnEditorControl;
         disabledWhen?: PhiRuntimeConditionExpression;
@@ -148,8 +160,8 @@ export type PhiTableSearchConfig = {
 export type PhiTablePaginationConfig = {
     enabled?: boolean;
     pageSize?: number;
-    pageSizeOptions?: readonly number[];
-    showSizeChanger?: boolean;
+    /** The page sizes a reader may switch between. Absent, the table offers no choice. */
+    pageSizes?: readonly number[];
 };
 export type PhiTableSortingConfig = {
     mode?: "none" | "single" | "multiple";
@@ -214,11 +226,6 @@ export type PhiTableStructureConfig = {
     indentSize?: number;
     expandColumnKey: string;
 };
-export type PhiTableSourceBinding = {
-    providerKey: PhiRuntimeDataProviderKey;
-    resourceKey: string;
-    params?: Record<string, unknown>;
-};
 export type PhiTableSummaryValue = string | number | boolean | null;
 export type PhiTableSummaryValueSource = {
     source: "provider";
@@ -264,8 +271,10 @@ export type PhiTableWidgetPresentation = PhiControlPresentationConfig & {
         title?: string;
         description?: string;
     };
-    bordered?: boolean;
-    showHeader?: boolean;
+    /** Lines around and between the cells. */
+    borders?: boolean;
+    /** The header row; shown unless this says `false`. */
+    header?: boolean;
     footer?: PhiTableFooterConfig;
     summary?: PhiTableSummaryConfig;
     row?: {
@@ -295,7 +304,7 @@ export type PhiTableWidgetConfig = {
     presentation: PhiTableWidgetPresentation;
     features: PhiTableWidgetFeatures;
     initialQuery?: PhiTableQuery;
-    source: PhiTableSourceBinding | null;
+    source: PhiProviderResourceSource | null;
     signalRoutes?: PhiSignalRouteSet | null;
 };
 export type PhiTableWidgetState = {
@@ -397,10 +406,7 @@ export type PhiTableProviderBindingFieldDefinition = {
     };
 };
 export type PhiTableProviderRowOrdering = "none" | "flat" | "tree";
-export type PhiTableProviderDragDropCapability = {
-    payloadType: `${string}/${string}`;
-    modes?: readonly ("before" | "after" | "child" | "replace" | "append")[];
-};
+export type PhiTableProviderDragDropCapability = PhiProviderDropTargetCapability;
 export type PhiTableProviderResourceDescriptor = {
     resourceKey: string;
     title: string;
@@ -411,6 +417,17 @@ export type PhiTableProviderResourceDescriptor = {
     bindingFields?: readonly PhiTableProviderBindingFieldDefinition[];
     query: PhiTableProviderQueryCapabilities;
     recordRead?: boolean;
+    /**
+     * Whether a row of this resource stands for something a person opens.
+     *
+     * Without it a row is inert and choosing one is the selection column's business, which is what a
+     * table of values is. A resource says this because only the resource knows: a conversation, a group
+     * and an invoice are things; an audit entry and a membership are records of things, and a click that
+     * appeared to open one would be a promise the page cannot keep.
+     *
+     * A boolean rather than a flag, to sit beside `recordRead` in the shape it already has.
+     */
+    rowActivation?: boolean;
     actions?: readonly PhiTableProviderActionCapability[];
     rowOrdering?: PhiTableProviderRowOrdering;
     dragSources?: readonly PhiTableProviderDragDropCapability[];
@@ -498,7 +515,7 @@ export type PhiTableProviderDropMutationRequest = PhiTableProviderMutationReques
         resourceKey: string;
         objectIdentities: readonly PhiTableRowIdentity[];
     };
-    dropMode: "before" | "after" | "child" | "replace" | "append";
+    dropMode: PhiProviderDropMode;
     targetParentRowIdentity: PhiTableRowIdentity | null;
     beforeRowIdentity: PhiTableRowIdentity | null;
     afterRowIdentity: PhiTableRowIdentity | null;
@@ -510,11 +527,6 @@ export declare class PhiTableProviderError extends Error {
 }
 export declare function readPhiTableQuery(value: unknown): PhiTableQuery | null;
 export declare function readPhiTableFilters(value: unknown): PhiTableQuery["filters"] | null;
-export declare function readPhiTableBindingParamsSignalValue(value: unknown): PhiTableBindingParamsSignalValue | null;
-export declare function readPhiTableSelectionSignalValue(value: unknown): PhiTableSelectionSignalValue | null;
-export declare function readPhiTableColumnOrderSignalValue(value: unknown): PhiTableColumnOrderSignalValue | null;
-export declare function readPhiTableExpansionSignalValue(value: unknown): PhiTableExpansionSignalValue | null;
-export declare function readPhiTableActionSignalValue(value: unknown): PhiTableActionSignalValue | null;
 export declare function readPhiTableProviderQueryResult(value: unknown): PhiTableProviderQueryResult | null;
 export declare function readPhiTableProviderMutationResult(value: unknown): PhiTableProviderMutationResult | null;
 /**