@phis/ui 0.2.1 → 0.4.0

package/types/cms-presets.d.ts

@@ -4,27 +4,30 @@ import type { PhiCmsInstanceId } from "./cms-instance-id";
 import type { PhiCmsContainerChromeConfig } from "./cms-container";
 import type { PhiRenderableBlockEffects, PhiRenderableBlockResponsiveSize, PhiRenderableBlockSize, PhiRenderableBlockVisibility } from "./renderable-block";
 import type { PhiCssLength } from "./length";
-import type { PhiShadow } from "./layout-style";
-export type PhiCmsAreaKey = "public" | "app" | "admin" | "builder" | "editor" | "accounting";
+import type { PhiLinkTarget } from "./references";
+import type { PhiCmsAreaKey } from "@phis/contracts/cms";
+export type { PhiCmsAreaKey };
 export type PhiCmsRegionKey = "header_top" | "header_main" | "header_bottom" | "sider_left" | "sider_right" | "hero" | "content" | "footer_top" | "footer_main" | "footer_bottom" | "drawer_left" | "drawer_right";
 export type PhiCmsRegionSource = "preset" | "fallback" | "page_override";
 export type PhiCmsLayerConfig = Record<string, unknown> & {
     zIndex?: number;
 };
 export type PhiCmsRegionConfig = Record<string, unknown> & PhiCmsContainerChromeConfig & {
-    borderRadius?: CSSProperties["borderRadius"];
     visibility?: PhiRenderableBlockVisibility;
+    /**
+     * The block runtime's live answer, merged in by the client renderer for the shell resolver; a stored
+     * config never states it (BUILDER.md, renderable blocks).
+     */
     enabled?: boolean;
     mode?: "light" | "dark";
-    sticky?: boolean;
-    fullHeight?: boolean;
-    collapsible?: boolean;
+    /**
+     * The Region's behaviour as `PhiCmsFlags` bits: `Sticky`, `FullHeight`, `Collapsible`, and `Collapsed`
+     * for the Builder preview. Read with `hasPhiFlag`; a Region stored on a Page has no row of its own, so
+     * its behaviour lives here and not on a row's `flags`.
+     */
     flags?: number;
     collapsedWidth?: CSSProperties["width"];
     collapseIcon?: string;
-    centered?: boolean;
-    mobileOnly?: boolean;
-    desktopOnly?: boolean;
     size?: PhiRenderableBlockResponsiveSize;
     minSize?: PhiRenderableBlockResponsiveSize;
     maxSize?: PhiRenderableBlockResponsiveSize;
@@ -35,16 +38,60 @@ export type PhiCmsRegionConfig = Record<string, unknown> & PhiCmsContainerChrome
     lineHeight?: CSSProperties["lineHeight"];
     offsetTop?: PhiCssLength;
     zIndex?: number;
+    /** Which of the Area's Pages show this Shell Region (`helpers/region-page-scope.ts`). */
+    pageScope?: PhiCmsRegionPageScope;
+    /** How `header_top` comes into view (`helpers/region-page-scope.ts`); every other Region ignores it. */
+    reveal?: PhiCmsRegionReveal;
 };
+/**
+ * Which Pages a Shell Region stands on (SHELL.md "Region visibility per Page").
+ *
+ * `all` is every Page of the Area, `root` the Area's own `/`. `include` and `exclude` name `entries`:
+ *
+ * - a Page, by its reference under `pageLinkTarget` -- never by its path, which an author may change at
+ *   any time. The `*LinkTarget` key is what lets the reference index see it (REFERENCES.md). With
+ *   `PhiCmsRegionPageScopeEntryFlag.Subtree` it stands for the Pages below it as well, which only a
+ *   Module Page can have.
+ * - a folder, by its path inside the Area. A folder is not a Page and has no identity of its own -- it is
+ *   the shared start of its Pages' paths -- so the path is all there is to name it by, and it takes
+ *   everything below it, including Pages added later.
+ */
+export declare const PHI_CMS_REGION_PAGE_SCOPE_MODES: readonly ["all", "root", "include", "exclude"];
+export type PhiCmsRegionPageScopeMode = (typeof PHI_CMS_REGION_PAGE_SCOPE_MODES)[number];
+export declare const PhiCmsRegionPageScopeEntryFlag: {
+    readonly Subtree: number;
+};
+export type PhiCmsRegionPageScopeEntry = {
+    pageLinkTarget: PhiLinkTarget;
+    flags?: number;
+} | {
+    folder: string;
+};
+export type PhiCmsRegionPageScope = {
+    mode: PhiCmsRegionPageScopeMode;
+    entries?: PhiCmsRegionPageScopeEntry[];
+};
+/**
+ * A Page scope as the browser asks it: every entry turned into an address inside the Area. The server
+ * resolves the references for each render; the browser compares the visitor's path against the result.
+ */
+export type PhiCmsResolvedRegionPageScope = {
+    mode: "root";
+} | {
+    mode: "include" | "exclude";
+    paths: string[];
+    prefixes: string[];
+};
+/**
+ * How a Region comes into view: `always` stands where it is, `hover` stays out of sight until the pointer
+ * reaches the top edge, `scroll-up` leaves while the visitor reads down and returns as soon as they
+ * scroll back.
+ */
+export declare const PHI_CMS_REGION_REVEAL_MODES: readonly ["always", "hover", "scroll-up"];
+export type PhiCmsRegionReveal = (typeof PHI_CMS_REGION_REVEAL_MODES)[number];
 export type PhiCmsLayoutConfig = PhiCmsLayerConfig & {
     gap?: number | string;
     padding?: number | string;
-    paddingInline?: number | string;
-    paddingBlock?: number | string;
-    background?: string;
-    shadow?: PhiShadow;
-    border?: boolean | CSSProperties["border"];
-    borderRadius?: number | string;
     align?: CSSProperties["alignItems"];
     justify?: CSSProperties["justifyContent"];
     wrap?: boolean | CSSProperties["flexWrap"];

package/types/cms-presets.js

@@ -1 +1,23 @@
-export {};
+/**
+ * Which Pages a Shell Region stands on (SHELL.md "Region visibility per Page").
+ *
+ * `all` is every Page of the Area, `root` the Area's own `/`. `include` and `exclude` name `entries`:
+ *
+ * - a Page, by its reference under `pageLinkTarget` -- never by its path, which an author may change at
+ *   any time. The `*LinkTarget` key is what lets the reference index see it (REFERENCES.md). With
+ *   `PhiCmsRegionPageScopeEntryFlag.Subtree` it stands for the Pages below it as well, which only a
+ *   Module Page can have.
+ * - a folder, by its path inside the Area. A folder is not a Page and has no identity of its own -- it is
+ *   the shared start of its Pages' paths -- so the path is all there is to name it by, and it takes
+ *   everything below it, including Pages added later.
+ */
+export const PHI_CMS_REGION_PAGE_SCOPE_MODES = ["all", "root", "include", "exclude"];
+export const PhiCmsRegionPageScopeEntryFlag = {
+    Subtree: 1 << 0,
+};
+/**
+ * How a Region comes into view: `always` stands where it is, `hover` stays out of sight until the pointer
+ * reaches the top edge, `scroll-up` leaves while the visitor reads down and returns as soon as they
+ * scroll back.
+ */
+export const PHI_CMS_REGION_REVEAL_MODES = ["always", "hover", "scroll-up"];

package/types/cms.d.ts

@@ -1,4 +1,5 @@
 import type { PhiRuntimeControllerSetting, PhiRuntimeModuleId } from "./cms-plugins";
+import type { PhiCmsAreaKey } from "@phis/contracts/cms";
 import type { PhiCmsInstanceId } from "./cms-instance-id";
 import type { PhiCmsPresetSource } from "./cms-module-descriptors";
 import type { PhiViewerAccessPolicy } from "./access";
@@ -36,7 +37,7 @@ export type PhiCmsPageNode = {
     layoutConfig: Record<string, unknown>;
 };
 export type PhiCmsPageRedirectTarget = {
-    area: "public" | "app" | "admin" | "builder" | "editor" | "accounting";
+    area: PhiCmsAreaKey;
     path: string;
 };
 export type PhiCmsPageRedirectConfig = {
@@ -95,7 +96,7 @@ export type PhiCmsResolvedContent = {
     id: number;
     type: number;
     slug: string;
-    /** The version the revision pins; `assetId`, `meta` and `textFields` are that version's. */
+    /** The version read -- published or current, as the tree was read; `assetId`, `meta` and `textFields` are its. */
     versionId: number;
     assetId: number | null;
     status: number;
@@ -104,12 +105,22 @@ export type PhiCmsResolvedContent = {
 };
 export type PhiCmsContentWidgetNode = PhiCmsNodeBase & {
     parentLayoutNodeId: PhiCmsInstanceId;
-    contentId: number | null;
     /**
-     * The content version this revision shows. The server sets it on every save that writes the content;
-     * a Widget that has written none yet has none.
+     * The current version of the Widget's bound content, as the tree was read: the base a structure save
+     * hands back, so that phi-server can tell an edit from a stale copy (phis-server CONTENT.md). `null`
+     * for a Widget without content. Its presence is also what tells a Widget node from a Layout node.
+     */
+    contentVersionId: number | null;
+    /**
+     * The field of the Widget's config that is its content, as the tree was stored or read. A save in a
+     * Canvas derives it afresh from the Widget's definition; a save outside one carries this.
+     */
+    contentBinding?: import("./cms-plugins").PhiCmsWidgetContentBinding | null;
+    /**
+     * The bound content in the stage the tree was read for: published on the live Site, current in the
+     * Builder, the Editor and previews. A Widget the Site created whose content was never published has
+     * none, and shows nothing there.
      */
-    contentVersionId?: number | null;
     resolvedContent?: PhiCmsResolvedContent | null;
 };
 export type PhiResolvedCmsPageTree = {
@@ -120,22 +131,31 @@ export type PhiResolvedCmsPageTree = {
     overlays: PhiCmsOverlayNode[];
     layoutNodes: PhiCmsLayoutNode[];
     contentWidgets: PhiCmsContentWidgetNode[];
+    controllerSettings?: PhiCmsTreeControllerSettings | null;
+};
+/**
+ * The Controllers a tree configures, and what it tells them -- the same field on a Page and on an Area.
+ *
+ * A Controller's receivers are the tree's to name, as every Widget's are, so the tree says them here
+ * beside the routes it writes for its nodes; a Controller that held Widget ids instead (a preset id
+ * map) only worked while one piece of code owned both ends. Each setting carries the tree's own scope
+ * as `mountScope` and is keyed by type and instance.
+ *
+ * Who runs the Controller is still its mount policy's answer
+ * (`components/runtime/runtime-controller-materialization.ts`): a setting for a `demand` Controller
+ * mounts it in the tree's scope; one for a Controller the Area already runs configures that one while
+ * the Page is shown; and one whose only asker is a deferred Area Overlay arrives with that Overlay.
+ * phis-server stores the field on every Page and Area revision (DB.md) and refuses `enabled`: a
+ * setting a tree stores is one it means.
+ */
+export type PhiCmsTreeControllerSettings = readonly PhiRuntimeControllerSetting[];
+export type PhiResolvedCmsRenderableTree = Pick<PhiResolvedCmsPageTree, "regions" | "overlays" | "layoutNodes" | "contentWidgets" | "controllerSettings"> & {
+    page?: PhiCmsPageNode | null;
     /**
-     * The Controllers this Page configures, and what it tells them.
-     *
-     * An Area has had this for as long as it has had Controllers -- `areaControllerSettings` on the
-     * module set -- and a Page had nothing. So a Page-scope Controller could be brought into being by a
-     * Widget asking for it and then be told nothing, which is why the Controllers on the conversations
-     * and groups Pages addressed their Widgets out of a preset id map: there was no other way to learn
-     * who to send to, and it holds only while the same code owns both ends.
-     *
-     * A Page says it here, beside the routes it already writes for every Widget on it. Demand mounting
-     * is untouched: a setting says what a Controller is configured with, not that it is running.
+     * Addresses something outside the tree's routes points at -- the shown Page's Tour (types/tours.ts).
+     * A frame is drawn live only where something can reach it, and a Tour step has to find its target.
      */
-    controllerSettings?: readonly PhiRuntimeControllerSetting[] | null;
-};
-export type PhiResolvedCmsRenderableTree = Pick<PhiResolvedCmsPageTree, "regions" | "overlays" | "layoutNodes" | "contentWidgets"> & {
-    page?: PhiCmsPageNode | null;
+    visualAnchorTargets?: readonly string[] | null;
 };
 export type PhiResolvedCmsPagePayload = {
     areaMask: number;
@@ -159,6 +179,7 @@ export type PhiResolvedCmsAreaPresetTree = {
     overlays: PhiCmsOverlayNode[];
     layoutNodes: PhiCmsLayoutNode[];
     contentWidgets: PhiCmsContentWidgetNode[];
+    controllerSettings?: PhiCmsTreeControllerSettings | null;
 };
 export type PhiResolvedCmsAreaPresetPayload = {
     areaMask: number;
@@ -168,6 +189,5 @@ export type PhiResolvedCmsAreaPresetPayload = {
 export type PhiCmsLayoutRenderNode = PhiCmsLayoutNode & {
     childLayouts: PhiCmsLayoutRenderNode[];
     childWidgets: PhiCmsContentWidgetNode[];
-    resolvedSlotTitles?: string[];
 };
 export {};

package/types/content-entries.d.ts

@@ -0,0 +1,76 @@
+import { type PhiContentEntryKind } from "../constants/content-entry-kinds";
+import type { PhiLinkTarget } from "./references";
+/**
+ * A word an entry is filed under: its address, which is its identity and stays as written, and its label in
+ * the page's language.
+ */
+export type PhiSiteContentEntryTerm = {
+    slug: string;
+    label: string;
+};
+/**
+ * The byline: the name the person chose to be shown under (or their first and last name) and, where they
+ * bound one, a picture that is already public. Core never answers an address here.
+ */
+export type PhiSiteContentEntryAuthor = {
+    name: string;
+    avatar: {
+        url: string;
+    } | null;
+};
+/**
+ * One published entry of a content type, as `GET /api/v1/entries/<kind>` answers it.
+ *
+ * The shape is Core's and the same for every kind: an entry lives in `site_content` under its kind's
+ * type, and what arrives here is already resolved for one locale and already filtered by publication date
+ * and expiry. Nothing in this package stores it ([phis-server CONTENT.md](../../phis-server/CONTENT.md)).
+ */
+export type PhiSiteContentEntry = {
+    /** The entry's public identity: its slug where it has one, its numeric id otherwise. */
+    id: string;
+    slug: string;
+    /** When the entry was published, or created where it never named a date. */
+    created: string;
+    /** When it stops being answered, or `null` where it does not. */
+    outdated: string | null;
+    title: string;
+    subtitle: string;
+    content: string;
+    /** Where the entry points: a Page of the Public Area or an address elsewhere (`REFERENCES.md`). */
+    link: PhiLinkTarget | null;
+    /** The category the entry is filed under, or `null` for none (`CONTENT_ENTRIES.md`, Terms). */
+    category: PhiSiteContentEntryTerm | null;
+    tags: readonly PhiSiteContentEntryTerm[];
+    /** Who the entry is attributed to, as a reader may see them, or `null` for no byline. */
+    author: PhiSiteContentEntryAuthor | null;
+    /**
+     * The language the body is written in, or `null` for the Site's own.
+     *
+     * Core answers `title` and `subtitle` already translated for the asked-for language, but not the body:
+     * Markdown is translated paragraph by paragraph where it is rendered, so its structure never reaches a
+     * provider. This is what the renderer needs to translate it the right way round.
+     */
+    sourceLocale: string | null;
+    /** Whether a reader in another language may be served a translation of this entry at all. */
+    translate: boolean;
+};
+/**
+ * One entry at its address with what a detail Page shows beside it, as
+ * `GET /api/v1/entries/<kind>/<slug>` answers it. `related` is there only where it was asked for.
+ */
+export type PhiSiteContentEntryPage = {
+    entry: PhiSiteContentEntry;
+    related: readonly PhiSiteContentEntry[] | null;
+};
+/**
+ * What the content entry record Provider answers (`PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntry`): one
+ * entry with its relatives, and the kind it is of, so a Widget bound to it needs to be told neither.
+ */
+export type PhiContentEntryRecord = PhiSiteContentEntryPage & {
+    kind: PhiContentEntryKind;
+};
+/**
+ * Reads a record a binding answered as an entry, or `null` where it is none -- a Widget bound to another
+ * Provider's record, which the Builder lets an author do.
+ */
+export declare function readPhiContentEntryRecord(value: unknown): PhiContentEntryRecord | null;

package/types/content-entries.js

@@ -0,0 +1,16 @@
+import { isPhiContentEntryKind } from "../constants/content-entry-kinds";
+import { isPhiRecord } from "../helpers/is-record";
+/**
+ * Reads a record a binding answered as an entry, or `null` where it is none -- a Widget bound to another
+ * Provider's record, which the Builder lets an author do.
+ */
+export function readPhiContentEntryRecord(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const record = value;
+    if (!isPhiContentEntryKind(record.kind) || !isPhiRecord(record.entry))
+        return null;
+    if (typeof record.entry.slug !== "string")
+        return null;
+    return value;
+}

package/types/core-runtime-controller.js

@@ -1,5 +1,6 @@
 import { PHI_SIGNAL_VALUE_SCHEMAS, } from "./signals";
 import { PHI_FEEDBACK_LEVELS, } from "./control";
+import { readPhiInternalPath } from "../helpers/internal-path";
 import { isPhiRecord } from "../helpers/is-record";
 export const PHI_CORE_RUNTIME_FEEDBACK_LEVELS = PHI_FEEDBACK_LEVELS;
 export const PHI_CORE_RUNTIME_NOTIFICATION_PLACEMENTS = [
@@ -99,11 +100,11 @@ export function readPhiCoreRuntimeNotificationSignalValue(signal) {
         : null;
 }
 export function readPhiCoreRuntimeNavigateValue(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return null;
     const record = value;
-    const path = typeof record.path === "string" ? record.path.trim() : "";
-    if (!path.startsWith("/") || path.startsWith("//"))
+    const path = readPhiInternalPath(record.path);
+    if (path === null)
         return null;
     return {
         path,

package/types/core-widget-placements.d.ts

@@ -1,3 +1,4 @@
+import type { PhiBulletListEntry, PhiBulletListStyle } from "../components/widgets/shared/bullet-list-vocabulary";
 import type { PhiRenderableBlockBase } from "./renderable-block";
 import type { PhiRuntimeConditionExpression } from "./runtime-condition";
 import type { PhiSignalRoute, PhiSignalValue } from "./signals";
@@ -10,11 +11,13 @@ import type { PhiLinkTarget } from "./references";
 import type { PhiMediaImageSourceConfig } from "./media";
 import type { PhiViewerAccessPolicy } from "./access";
 import type { PhiWidgetFontFamilyKey, PhiWidgetFontSizeKey } from "./site-theme";
-import type { PhiTableQuery, PhiTableWidgetFeatures, PhiTableWidgetPresentation } from "./table-widget";
+import type { PhiTableQuery, PhiTableWidgetConfig, PhiTableWidgetFeatures, PhiTableWidgetPresentation } from "./table-widget";
 import type { PhiButtonVariant } from "../components/widgets/config/button-variant";
 import type { PhiTextTone } from "../components/widgets/config/text-tone";
 import type { PhiCommonControlActionKey } from "../components/widgets/label-types/common-controls";
 import type { PhiMaskConfig } from "../components/widgets/config/mask";
+import type { PhiSpacingScaleKey } from "../components/widgets/config/spacing-options";
+import type { PhiCardVariant } from "../components/widgets/shared/card-vocabulary";
 import type { PhiControlBadgeConfig, PhiControlConfig } from "../components/widgets/config/control-signal-config";
 /**
  * The part of a placement every Widget shares, whatever it is.
@@ -36,7 +39,6 @@ export type PhiWidgetPlacementSignalRoutes = {
 };
 /** A Control's own settings in a placement; its routes are the envelope's. */
 type PhiControlPlacement = Omit<PhiControlConfig, "signalRoutes">;
-export type PhiMarkdownSpacingKey = "none" | "xxs" | "xs" | "sm" | "base" | "md" | "lg" | "xl" | "xxl";
 /** Logical, not left and right: a Site in an RTL locale reads "start" as the right-hand edge. */
 export type PhiMarkdownTextAlign = "start" | "center" | "end" | "justify";
 export type PhiMarkdownWidgetPlacement = PhiWidgetPlacementBase & {
@@ -46,11 +48,13 @@ export type PhiMarkdownWidgetPlacement = PhiWidgetPlacementBase & {
     sourceLocale?: string;
     revalidateSeconds?: number;
     textAlign?: PhiMarkdownTextAlign;
-    textBlockSpacingBefore?: PhiMarkdownSpacingKey;
-    textBlockSpacingAfter?: PhiMarkdownSpacingKey;
-    headingBlockSpacingBefore?: PhiMarkdownSpacingKey;
-    headingBlockSpacingAfter?: PhiMarkdownSpacingKey;
+    textBlockSpacingBefore?: PhiSpacingScaleKey;
+    textBlockSpacingAfter?: PhiSpacingScaleKey;
+    headingBlockSpacingBefore?: PhiSpacingScaleKey;
+    headingBlockSpacingAfter?: PhiSpacingScaleKey;
+    headingOffset?: number;
     tocKey?: string;
+    list?: PhiBulletListStyle;
 };
 /** The marks a Simple Text can carry, each on or off. */
 export declare const PHI_SIMPLE_TEXT_MARKS: readonly ["bold", "italic", "underline", "strike", "code"];
@@ -73,12 +77,13 @@ export type PhiDescriptionWidgetPlacement = PhiWidgetPlacementBase & {
     title?: string;
     description?: string;
     asideTitle?: string;
-    asideItems?: string[];
+    asideItems?: PhiBulletListEntry[];
+    asideList?: PhiBulletListStyle;
     footer?: string;
     tone?: PhiTextTone;
 };
 export type PhiButtonWidgetPlacement = PhiWidgetPlacementBase & PhiControlPlacement & PhiControlBadgeConfig & {
-    actionKey?: PhiCommonControlActionKey;
+    action?: PhiCommonControlActionKey;
     label?: string;
     tooltip?: string;
     icon?: string;
@@ -123,6 +128,7 @@ export type PhiTableWidgetPlacement = PhiWidgetPlacementBase & {
     presentation?: Partial<PhiTableWidgetPresentation>;
     features?: PhiTableWidgetFeatures;
     initialQuery?: PhiTableQuery;
+    fixedFilters?: PhiTableWidgetConfig["fixedFilters"];
     source?: PhiProviderResourceSource | null;
 };
 /**
@@ -183,9 +189,9 @@ export type PhiCmsFormWidgetFeedbackConfig = {
  *
  * `presentation` is the switch as well as the step: absent, or anything outside the three names, is no
  * box at all -- no ground and no inset -- which is what every Form placed before this one has and keeps.
- * That matters more than it sounds: the Login and its siblings stand in a Split Card slot that already
- * paints a ground, so a box there would be a plate inside a plate, and an inset would move the query
- * container the fields are measured in for nothing.
+ * That matters more than it sounds: the Login and its siblings stand in a Split Card half whose Layout
+ * already paints a card's ground, so a box there would be a plate inside a plate, and an inset would
+ * move the query container the fields are measured in for nothing.
  *
  * The three names are one ladder -- how far the box separates itself from what is behind it -- and each
  * step is stated once. `card` and `panel` deliberately share a ground: the inset already says how deep
@@ -259,12 +265,22 @@ export type PhiCmsCollectionCardPresentation = {
     meta?: string;
     /** A path to something already servable: a Media delivery path or a URL. */
     imageUrl?: string;
-    /** The same, for the small mark beside the title. A cover and a mark are different pictures. */
-    iconUrl?: string;
+    /**
+     * The mark beside the title or at the top: a field holding an icon name, or a Site path to a picture
+     * (a Media delivery path), which the card draws as an `asset:` icon. A cover and a mark are different
+     * pictures.
+     */
+    icon?: string;
+    /** The figure of a `stat` card. */
+    value?: string;
     href?: string;
     actionLabel?: string;
     actionHref?: string;
-    variant?: "default" | "compact" | "featured";
+    variant?: PhiCardVariant;
+    /** Every card in the View draws this body; `stat` needs `value`. */
+    body?: "text" | "stat";
+    /** A field whose truth marks the card as highlighted. */
+    highlight?: string;
 };
 export type PhiCollectionViewWidgetPlacement = PhiWidgetPlacementBase & {
     presentation?: {
@@ -305,32 +321,53 @@ export type PhiCollectionViewWidgetPlacement = PhiWidgetPlacementBase & {
     /** A Render Client other than the one the bound provider ships, registered by any Module. */
     itemRendererKey?: string | null;
 };
-export type PhiCommandToolbarButtonEmitConfig = {
+export type PhiCommandButtonEmitConfig = {
     capabilityId: string;
     value?: PhiSignalValue;
 };
-export type PhiCommandToolbarButtonConfig = {
+/**
+ * One button of a Widget that holds several, each its own signal subcontrol.
+ *
+ * The badge is the Button Widget's badge, per button: what a Preset states here is drawn until a
+ * `badge/change` addressed to the button says otherwise.
+ */
+export type PhiCommandButtonConfig = PhiControlBadgeConfig & {
     key: string;
-    emits: PhiCommandToolbarButtonEmitConfig[];
+    emits: PhiCommandButtonEmitConfig[];
     accessPolicy?: PhiViewerAccessPolicy;
-    actionKey?: PhiCommonControlActionKey;
+    action?: PhiCommonControlActionKey;
     label?: string;
     tooltip?: string;
     icon?: string;
     display?: "icon" | "label" | "icon-label";
     danger?: boolean;
     disabled?: boolean;
+    /** Shown as it is, not greyed out, and sends nothing when pressed. */
+    readOnly?: boolean;
     variant?: PhiButtonVariant;
 };
-export type PhiCommandToolbarWidgetPlacement = PhiWidgetPlacementBase & PhiControlPlacement & {
+/**
+ * Without the Control's own Read only and Disabled: each button has its own, and the whole toolbar is
+ * switched by `enabled/change`, which every renderable block receives.
+ */
+export type PhiCommandToolbarWidgetPlacement = PhiWidgetPlacementBase & Omit<PhiControlPlacement, "readOnly" | "disabled"> & {
     compact?: boolean;
     wrap?: boolean;
     showLabels?: boolean;
-    buttons?: PhiCommandToolbarButtonConfig[];
+    buttons?: PhiCommandButtonConfig[];
+};
+/**
+ * One conversation, read: Core's, for every Module that runs conversations of its own kind. Which one it
+ * shows arrives on the `thread` channel (`signals/thread-selection`) or as `?thread=`. With `reply` it
+ * offers a Reply in its heading, said as a row action with the thread as the row -- route it to a dialog
+ * holding Core's Reply Form (`PHI_SHARED_FORM_IDS.threadReply`) with the thread inbox as its `source`.
+ */
+export type PhiThreadConversationWidgetPlacement = PhiWidgetPlacementBase & {
+    reply?: boolean;
+    padding?: number | string;
 };
 export type PhiThemeModeSwitchSize = "small" | "medium";
 export type PhiThemeModeSwitchWidgetPlacement = PhiWidgetPlacementBase & {
-    label?: string;
     controlSize?: PhiThemeModeSwitchSize;
 };
 /**
@@ -358,6 +395,7 @@ export type PhiCoreWidgetPlacements = {
     form: PhiFormWidgetPlacement;
     "collection-view": PhiCollectionViewWidgetPlacement;
     "command-toolbar": PhiCommandToolbarWidgetPlacement;
+    "thread-conversation": PhiThreadConversationWidgetPlacement;
     "theme-mode-switch": PhiThemeModeSwitchWidgetPlacement;
     "draft-status": PhiDraftStatusWidgetPlacement;
 };

package/types/dashboard-cards.d.ts

@@ -1,4 +1,5 @@
 import type { PhiCmsAreaKey } from "../constants/cms-areas";
+import type { PhiTimelineEntry } from "@phis/contracts/timeline";
 import type { PhiAccessViewer, PhiViewerAccessPolicy } from "./access";
 /**
  * What a Module offers a Dashboard, and what it is asked for afterwards.
@@ -26,13 +27,18 @@ export declare function createPhiDashboardCardId(moduleId: string, leaf: string)
 /**
  * The card forms Core draws.
  *
- * `stat` is the one every contributor in sight needs: a figure, what it is, and where to go for more.
- * The form names a renderer and the payload fills it, so adding one later is a card View and a case in
- * the reader -- but a form Core offers is a promise it then keeps, so it gets offered when somebody has
- * the case rather than in advance. DASHBOARD.md section 9 leaves `list` and a series card open on
- * exactly those terms.
+ * `stat` is a figure, what it is, and where to go for more. `list` is a handful of entries -- what
+ * changed, what is waiting -- each a line with an optional time and tone; the Builder's Dashboard is the
+ * case that asked for it, because what a structure author looks for first is what is open rather than
+ * how many. The form names a renderer and the payload fills it, and a form Core offers is a promise it
+ * then keeps: a series card stays open until somebody has a series (DASHBOARD.md section 9).
  */
-export type PhiDashboardCardForm = "stat";
+export type PhiDashboardCardForm = "stat" | "list";
+/**
+ * How many entries a `list` card draws. A card shows little and leads out (DASHBOARD.md section 2); a
+ * provider that has more says so in `meta` and lets the card's target show the rest.
+ */
+export declare const PHI_DASHBOARD_CARD_LIST_LIMIT = 5;
 export type PhiDashboardCardDescriptor = {
     cardId: PhiDashboardCardId;
     form: PhiDashboardCardForm;
@@ -89,8 +95,14 @@ export type PhiDashboardCardDescriptor = {
  */
 export type PhiDashboardCardPayload = {
     cardId: PhiDashboardCardId;
-    /** The figure, which takes the place the descriptor's title held while it was loading. */
+    /** A `stat` card's figure, drawn under the descriptor's title. */
     value?: string;
+    /**
+     * A `list` card's entries, newest or most pressing first, at most `PHI_DASHBOARD_CARD_LIST_LIMIT` of
+     * them drawn. The Timeline's entry (`@phis/contracts/timeline`), so a time is stated as an instant the
+     * card formats in the page's locale, or in words where words are what the provider has.
+     */
+    entries?: PhiTimelineEntry[];
     description?: string;
     meta?: string;
     error?: string | null;
@@ -149,4 +161,13 @@ export type PhiDashboardCardRow = {
     description?: string;
     mark?: string;
     href?: string;
+    /**
+     * The card's first payload, resolved with the list.
+     *
+     * The list used to carry descriptors only, and every card then asked for its payload in a request
+     * of its own -- each resolving the locale, the viewer, the capabilities and the Area again, so a
+     * Dashboard of five cards cost six request chains. The first paint comes with the list now; a
+     * refresh asks the card's own endpoint, one card at a time (DASHBOARD.md section 3).
+     */
+    payload?: PhiDashboardCardPayload;
 };

package/types/dashboard-cards.js

@@ -13,3 +13,8 @@ export function isPhiDashboardCardId(value) {
 export function createPhiDashboardCardId(moduleId, leaf) {
     return createPhiModuleIdentifier(moduleId, "cards", leaf, "segment");
 }
+/**
+ * How many entries a `list` card draws. A card shows little and leads out (DASHBOARD.md section 2); a
+ * provider that has more says so in `meta` and lets the card's target show the rest.
+ */
+export const PHI_DASHBOARD_CARD_LIST_LIMIT = 5;

package/types/dimension.js

@@ -1,6 +1,7 @@
+import { isPhiRecord } from "../helpers/is-record";
 import { readPhiCssLengthPart, serializePhiCssLength } from "./length";
 export function readPhiDimensionValue(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;

package/types/draft-status.js

@@ -1,8 +1,9 @@
+import { isPhiRecord } from "../helpers/is-record";
 function isPhiDraftStatus(value) {
     return value === "unsaved" || value === "draft" || value === "published" || value === "error";
 }
 export function readPhiDraftStatusSignalValue(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;

package/types/form-descriptor.d.ts

@@ -1,7 +1,7 @@
 import type { PhiCmsConfigField } from "./cms-plugins";
 import type { PhiRuntimeModuleId } from "./cms-plugins";
 import type { PhiFormProviderKey } from "@phis/contracts/forms";
-import type { PhiFormSubmitCategory, PhiFormSubmitMethod, PhiFormSubmitTransport } from "../gateway/form-submit";
+import type { PhiFormSubmitCategory, PhiFormSubmitMethod, PhiFormSubmitTransport } from "./form-submit-route";
 export { PHI_FORM_DEFAULT_SUBMIT_LABEL, PHI_FORM_DESCRIPTOR_SCHEMA_VERSION, PHI_FORM_GRID_TRACKS, type PhiFormDescriptor, type PhiFormFieldDescriptor, type PhiFormFieldPlacementDescriptor, type PhiFormGridRange, type PhiFormLabelSetKey, type PhiFormLayoutDescriptor, type PhiFormLogicalAlignment, type PhiFormOptionDescriptor, type PhiFormProviderKey, type PhiFormResponsiveGridRange, type PhiFormSubmitDescriptor, type PhiFormSuccessDescriptor, type PhiFormTextDescriptor, type PhiFormValidationRuleDescriptor, } from "@phis/contracts/forms";
 export type PhiFormHandlerPhase = "submit" | "confirm" | "preview";
 export type PhiFormHandlerCredentialPolicy = "none" | "site-session" | "auth-link";