@phis/ui 0.1.0 → 0.2.0

package/types/collection-view-widget.d.ts

@@ -0,0 +1,67 @@
+import type { PhiCmsCollectionCardPresentation, PhiCmsCollectionFilterPresentation, PhiCmsCollectionToolbarActionPresentation, PhiCmsCollectionViewMode } from "./core-widget-placements";
+import type { PhiControlSize } from "./control";
+import type { PhiCollectionProviderQuery } from "./collection-provider";
+import type { PhiProviderResourceSource } from "./runtime-data-provider";
+import type { PhiSignalRouteSet } from "./signals";
+import type { PhiCssLength } from "./length";
+import type { PhiCmsWidgetConfigBase } from "../components/widgets/config/parser-primitives";
+/**
+ * A Collection View's parsed config, as the item renderer it hands its items to receives it.
+ *
+ * The Foundation's because the renderer is often not the Collection View's Module: a Module registers a
+ * collection item renderer for its own rows -- the Dashboard's cards, the Media library's tiles -- and
+ * the View passes it this config with the binding. A renderer that had to import the Core Widget's
+ * config to type its props would be a Module importing another Module.
+ */
+export type PhiCmsCollectionViewWidgetConfig = PhiCmsWidgetConfigBase & {
+    presentation: {
+        title?: string;
+        description?: string;
+        /** Read by the card View and by no other: a View that draws something else ignores it. */
+        card?: PhiCmsCollectionCardPresentation;
+        mode: PhiCmsCollectionViewMode;
+        gap?: PhiCssLength;
+        minColumnWidth?: PhiCssLength;
+        emptyDescription?: string;
+        controlSize?: PhiControlSize;
+        labels?: Record<string, unknown>;
+    };
+    features: {
+        tools: {
+            mode: "self-contained" | "external";
+            reload?: boolean;
+            reset?: boolean;
+        };
+        search?: {
+            enabled: boolean;
+            placeholder?: string;
+            minWidth?: PhiCssLength;
+        };
+        filters?: PhiCmsCollectionFilterPresentation[];
+        actions?: {
+            toolbar?: PhiCmsCollectionToolbarActionPresentation[];
+        };
+        pagination?: {
+            enabled: boolean;
+            pageSize?: number;
+            /** The page sizes a reader may switch between. Absent, the collection offers no choice. */
+            pageSizes?: readonly number[];
+            /** The short pager: previous, the page, next. */
+            compact?: boolean;
+        };
+    };
+    initialQuery?: PhiCollectionProviderQuery;
+    source: PhiProviderResourceSource | null;
+    /**
+     * A renderer other than the one the bound provider ships.
+     *
+     * The provider's resource names the Render Client it comes with, and that is what draws the items
+     * unless a Site says otherwise here. A Module that does not own the resource registers another Client
+     * for the same items under its own key, and naming that key is how a Site chooses it -- which is the
+     * only way to show somebody else's objects your way without forking the provider.
+     *
+     * A key whose Module is not active in this Area is reported in the block rather than thrown.
+     */
+    itemRendererKey?: string | null;
+    signalRoutes?: PhiSignalRouteSet | null;
+};

package/types/collection-view-widget.js

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

package/types/core-runtime-controller.js

@@ -1,5 +1,6 @@
 import { PHI_SIGNAL_VALUE_SCHEMAS, } from "./signals";
 import { PHI_FEEDBACK_LEVELS, } from "./control";
+import { isPhiRecord } from "../helpers/is-record";
 export const PHI_CORE_RUNTIME_FEEDBACK_LEVELS = PHI_FEEDBACK_LEVELS;
 export const PHI_CORE_RUNTIME_NOTIFICATION_PLACEMENTS = [
     "top",
@@ -9,9 +10,6 @@ export const PHI_CORE_RUNTIME_NOTIFICATION_PLACEMENTS = [
     "bottomLeft",
     "bottomRight",
 ];
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
 function hasOnlyKeys(value, allowedKeys) {
     return Object.keys(value).every((key) => allowedKeys.includes(key));
 }
@@ -37,7 +35,7 @@ function readNotificationPlacement(value) {
         : null;
 }
 export function readPhiCoreRuntimeNotificationValue(value) {
-    if (!isRecord(value) || !hasOnlyKeys(value, [
+    if (!isPhiRecord(value) || !hasOnlyKeys(value, [
         "level",
         "title",
         "description",
@@ -75,7 +73,7 @@ export function readPhiCoreRuntimeNotificationValue(value) {
     };
 }
 export function readPhiCoreRuntimeMessageValue(value) {
-    if (!isRecord(value) || !hasOnlyKeys(value, ["level", "content", "durationSeconds"])) {
+    if (!isPhiRecord(value) || !hasOnlyKeys(value, ["level", "content", "durationSeconds"])) {
         return null;
     }
     const level = readFeedbackLevel(value.level);

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

@@ -0,0 +1,365 @@
+import type { PhiRenderableBlockBase } from "./renderable-block";
+import type { PhiRuntimeConditionExpression } from "./runtime-condition";
+import type { PhiSignalRoute, PhiSignalValue } from "./signals";
+import type { PhiCssLength } from "./length";
+import type { PhiControlSize } from "./control";
+import type { PhiCollectionProviderQuery } from "./collection-provider";
+import type { PhiProviderResourceSource } from "./runtime-data-provider";
+import type { PhiFormId } from "./form-id";
+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 { 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 { PhiControlBadgeConfig, PhiControlConfig } from "../components/widgets/config/control-signal-config";
+/**
+ * The part of a placement every Widget shares, whatever it is.
+ *
+ * The block base is applied by the slot frame from the node's raw config, not by the Widget, which is
+ * why it holds for every Widget alike -- a Widget whose own type forgot it still gets it. Render and
+ * debug modes are left out: the renderer sets them, an author does not. Node flags such as
+ * `NoTranslate` are not config at all and stay on the node.
+ */
+export type PhiWidgetPlacementBase = Omit<PhiRenderableBlockBase, "renderMode" | "debugMode"> & {
+    /** Shows the Widget only while the condition holds; the renderer evaluates it for every Widget. */
+    visibleWhen?: PhiRuntimeConditionExpression;
+    signalRoutes?: PhiWidgetPlacementSignalRoutes | null;
+};
+/** The routes a placement wires. Read-only lists, so a Preset can build them from shared constants. */
+export type PhiWidgetPlacementSignalRoutes = {
+    emits?: readonly PhiSignalRoute[] | null;
+    listens?: readonly PhiSignalRoute[] | null;
+};
+/** 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 & {
+    sourceMode?: "inline" | "url";
+    markdown?: string;
+    sourceUrl?: string;
+    sourceLocale?: string;
+    revalidateSeconds?: number;
+    textAlign?: PhiMarkdownTextAlign;
+    textBlockSpacingBefore?: PhiMarkdownSpacingKey;
+    textBlockSpacingAfter?: PhiMarkdownSpacingKey;
+    headingBlockSpacingBefore?: PhiMarkdownSpacingKey;
+    headingBlockSpacingAfter?: PhiMarkdownSpacingKey;
+    tocKey?: string;
+};
+/** The marks a Simple Text can carry, each on or off. */
+export declare const PHI_SIMPLE_TEXT_MARKS: readonly ["bold", "italic", "underline", "strike", "code"];
+export type PhiSimpleTextMark = (typeof PHI_SIMPLE_TEXT_MARKS)[number];
+export type PhiSimpleTextWidgetPlacement = PhiWidgetPlacementBase & {
+    text?: string;
+    href?: string;
+    icon?: string;
+    color?: string;
+    fontFamily?: PhiWidgetFontFamilyKey;
+    fontSize?: PhiWidgetFontSizeKey;
+    external?: boolean;
+    newTab?: boolean;
+    tone?: PhiTextTone;
+    marks?: PhiSimpleTextMark[];
+    disabled?: boolean;
+};
+export type PhiDescriptionWidgetPlacement = PhiWidgetPlacementBase & {
+    eyebrow?: string;
+    title?: string;
+    description?: string;
+    asideTitle?: string;
+    asideItems?: string[];
+    footer?: string;
+    tone?: PhiTextTone;
+};
+export type PhiButtonWidgetPlacement = PhiWidgetPlacementBase & PhiControlPlacement & PhiControlBadgeConfig & {
+    actionKey?: PhiCommonControlActionKey;
+    label?: string;
+    tooltip?: string;
+    icon?: string;
+    value?: string;
+    variant?: PhiButtonVariant;
+    linkTarget?: PhiLinkTarget;
+    danger?: boolean;
+};
+export type PhiImageWidgetPreviewMode = "none" | "native" | "lightbox";
+export type PhiImageWidgetFit = "cover" | "contain" | "fill";
+export type PhiImageWidgetSize = {
+    width?: number | string;
+    height?: number | string;
+};
+export type PhiImageWidgetPlacement = PhiWidgetPlacementBase & PhiMediaImageSourceConfig & {
+    fit?: PhiImageWidgetFit;
+    objectPosition?: string;
+    title?: string;
+    imageSize?: PhiImageWidgetSize;
+    borderTopLeftRadius?: number | string;
+    borderTopRightRadius?: number | string;
+    borderBottomLeftRadius?: number | string;
+    borderBottomRightRadius?: number | string;
+    mask?: PhiMaskConfig;
+};
+export type PhiIconWidgetPlacement = PhiWidgetPlacementBase & {
+    icon?: string;
+    color?: string;
+};
+/** Nothing of its own: a Spacer is its block, and the block is the envelope. */
+export type PhiSpacerWidgetPlacement = PhiWidgetPlacementBase;
+export type PhiHtmlWidgetPlacement = PhiWidgetPlacementBase & {
+    html?: string;
+    sourceMode?: "inline" | "url";
+    sourceUrl?: string;
+    sourceLocale?: string;
+    revalidateSeconds?: number;
+    fontFamily?: PhiWidgetFontFamilyKey;
+    fontSize?: PhiWidgetFontSizeKey;
+};
+export type PhiTableWidgetPlacement = PhiWidgetPlacementBase & {
+    presentation?: Partial<PhiTableWidgetPresentation>;
+    features?: PhiTableWidgetFeatures;
+    initialQuery?: PhiTableQuery;
+    source?: PhiProviderResourceSource | null;
+};
+/**
+ * Whether this placement draws the form's own submit.
+ *
+ * `inline` draws the button the descriptor describes (`submit`: what it says, where on the grid it
+ * stands). `external` draws none: the form is submitted by whoever holds its `submit` capability -- a
+ * Button Widget, an Overlay footer, a toolbar -- or by Enter where `submitOnEnter` allows it. Either way
+ * there is one path; the button is only one more sender on the same channel.
+ *
+ * The placement answers this and not the form, because the same form stands on a page of its own with
+ * a button under its fields and in a dialog whose footer carries the button.
+ */
+export type PhiCmsFormWidgetSubmitPlacement = "inline" | "external";
+/**
+ * A way out of the form, standing where its submit stands.
+ *
+ * "Forgot password" and "Create account" are not fields and not commands -- they are the two other
+ * things a person at a sign-in might want. They belong to the Widget for the same reason the submit
+ * does: whether they are offered, and in which column they sit, is the placement's decision. Being in
+ * the Widget is also the only way they can line up under the inputs, because the label column is a
+ * property of the form's own grid and nothing outside it can read where that column ends.
+ */
+export type PhiCmsFormWidgetLinkConfig = {
+    /** Names the link's label in the form's label set, as `actions.<key>Label`. */
+    key: string;
+    href: string;
+    /** A published Module fact this link depends on, such as `auth.registration`. */
+    requiresFeature?: string;
+};
+/**
+ * Whether a submit is worth saying out loud, and how.
+ *
+ * A Form already shows what happened where it stands: an error above the fields, and a success panel
+ * where its descriptor has one. That is enough on a Page somebody came to in order to submit it. It is
+ * not enough in Settings, where a panel is one of several and a switch that saves on change has nothing
+ * to show at all -- the Widget that used to own the profile name reported through the application
+ * feedback, and the registered Form that replaced it said nothing.
+ *
+ * So the placement decides, the way it decides whether there is a submit button: a Form on a Page of
+ * its own stays quiet, a Form in a Settings panel reports. `successText` is what a success says where
+ * the descriptor says nothing, already translated by whoever placed it.
+ */
+export type PhiCmsFormWidgetFeedbackConfig = {
+    mode: "message" | "notification";
+    successText?: string;
+};
+/**
+ * The box the Widget draws around its Form, or none at all.
+ *
+ * A Form describes fields. Whether it stands in a box is the same kind of question as whether it carries
+ * its own submit -- the placement's, not the Form's -- which is why it is configured here and appears in
+ * no descriptor. It exists because the box was being built by hand: a client Widget with its own Card,
+ * its own inset and, in one revision, its own Ant Design colour variable, standing beside a Form that
+ * could not have a box at all. What draws it is `PhiCardControl`, so the Theme's surface shape reaches it
+ * through the same component token every other surface reads and the ground and the frame are the
+ * Theme's -- nothing here names a colour or a corner.
+ *
+ * `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.
+ *
+ * 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
+ * the box sits, and a second ground would say it again and drift the moment one of the two gains a
+ * source the other has not.
+ */
+export type PhiCmsFormWidgetCardConfig = {
+    /**
+     * `card` is a box on a Page of its own; `panel` is the same box at the inset of chrome -- a Settings
+     * section; `wash` is the quietest filling the Theme has with no frame at all, for a Form that already
+     * stands on a container and only needs its fields set off from it.
+     */
+    presentation: "card" | "panel" | "wash";
+    /** A heading in a bar above the fields, already translated by whoever placed the Form. */
+    title: string | null;
+    /** The box's own inset, where the Theme's answer for this box is not the right one. */
+    padding: number | string | null;
+};
+export type PhiFormWidgetPlacement = PhiWidgetPlacementBase & {
+    formId?: PhiFormId | null;
+    submit?: PhiCmsFormWidgetSubmitPlacement;
+    submitOnEnter?: boolean;
+    card?: (Pick<PhiCmsFormWidgetCardConfig, "presentation"> & Partial<Omit<PhiCmsFormWidgetCardConfig, "presentation">>) | null;
+    maxFormWidth?: number | string;
+    feedback?: PhiCmsFormWidgetFeedbackConfig | null;
+    links?: readonly PhiCmsFormWidgetLinkConfig[];
+    /** Prepared for the Form Builder: the placement's own settings for the Form it shows. */
+    formConfig?: Record<string, unknown>;
+    execution?: {
+        mode?: "handler" | "signal";
+        phase?: "submit" | "confirm";
+    };
+    source?: PhiProviderResourceSource | null;
+    /** Absent is a single-record form; the Form Widget's config says why that is an answer. */
+    openActionKey?: string;
+};
+export type PhiCmsCollectionViewMode = "grid" | "masonry" | "stack";
+export type PhiCmsCollectionFilterControl = "select" | "multi-select" | "cascader";
+export type PhiCmsCollectionFilterPresentation = {
+    key: string;
+    control: PhiCmsCollectionFilterControl;
+    placeholder?: string;
+    width?: PhiCssLength;
+    minWidth?: PhiCssLength;
+    actions?: PhiCmsCollectionToolbarActionPresentation[];
+};
+export type PhiCmsCollectionToolbarActionPresentation = {
+    key: string;
+    label?: string;
+    description?: string;
+    icon?: string;
+    display?: "icon" | "label" | "icon-label";
+    mode?: "normal" | "primary" | "danger";
+};
+/**
+ * Where a card takes each of its parts from, as paths into one item.
+ *
+ * The Card Widget already knows what a card is -- eyebrow, title, description, meta, a cover, a link --
+ * and a Collection already knows how to lay items out. What was missing between them is only this: which
+ * field of a row is the title. Stating it here rather than in the provider keeps it where the rest of
+ * the presentation lives, so a Site can point the title at another field without anybody writing code,
+ * exactly as a Table's columns are chosen from the fields a provider offers.
+ *
+ * A resource that outgrows this ships its own View instead; that is one field in its registration, and
+ * the Media library is the example of a domain that needed one.
+ */
+export type PhiCmsCollectionCardPresentation = {
+    eyebrow?: string;
+    title?: string;
+    description?: string;
+    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;
+    href?: string;
+    actionLabel?: string;
+    actionHref?: string;
+    variant?: "default" | "compact" | "featured";
+};
+export type PhiCollectionViewWidgetPlacement = PhiWidgetPlacementBase & {
+    presentation?: {
+        title?: string;
+        description?: string;
+        card?: PhiCmsCollectionCardPresentation;
+        mode?: PhiCmsCollectionViewMode;
+        gap?: PhiCssLength;
+        minColumnWidth?: PhiCssLength;
+        emptyDescription?: string;
+        controlSize?: PhiControlSize;
+        labels?: Record<string, unknown>;
+    };
+    features?: {
+        tools?: {
+            mode?: "self-contained" | "external";
+            reload?: boolean;
+            reset?: boolean;
+        };
+        search?: {
+            enabled: boolean;
+            placeholder?: string;
+            minWidth?: PhiCssLength;
+        };
+        filters?: PhiCmsCollectionFilterPresentation[];
+        actions?: {
+            toolbar?: PhiCmsCollectionToolbarActionPresentation[];
+        };
+        pagination?: {
+            enabled: boolean;
+            pageSize?: number;
+            pageSizes?: readonly number[];
+            compact?: boolean;
+        };
+    };
+    initialQuery?: PhiCollectionProviderQuery;
+    source?: PhiProviderResourceSource | null;
+    /** A Render Client other than the one the bound provider ships, registered by any Module. */
+    itemRendererKey?: string | null;
+};
+export type PhiCommandToolbarButtonEmitConfig = {
+    capabilityId: string;
+    value?: PhiSignalValue;
+};
+export type PhiCommandToolbarButtonConfig = {
+    key: string;
+    emits: PhiCommandToolbarButtonEmitConfig[];
+    accessPolicy?: PhiViewerAccessPolicy;
+    actionKey?: PhiCommonControlActionKey;
+    label?: string;
+    tooltip?: string;
+    icon?: string;
+    display?: "icon" | "label" | "icon-label";
+    danger?: boolean;
+    disabled?: boolean;
+    variant?: PhiButtonVariant;
+};
+export type PhiCommandToolbarWidgetPlacement = PhiWidgetPlacementBase & PhiControlPlacement & {
+    compact?: boolean;
+    wrap?: boolean;
+    showLabels?: boolean;
+    buttons?: PhiCommandToolbarButtonConfig[];
+};
+export type PhiThemeModeSwitchSize = "small" | "medium";
+export type PhiThemeModeSwitchWidgetPlacement = PhiWidgetPlacementBase & {
+    label?: string;
+    controlSize?: PhiThemeModeSwitchSize;
+};
+/**
+ * Wired, not configured: the placement's routes name the Controller whose draft it shows -- `request`
+ * where it asks on mount, `status` what it hears back.
+ */
+export type PhiDraftStatusWidgetPlacement = PhiWidgetPlacementBase;
+/**
+ * The placement contract of each Core Widget, by type key.
+ *
+ * A Core Widget missing here is placed untyped until it is added -- Card among them, whose config is
+ * still changing. The node factories read this map: a Core type key listed here takes its placement
+ * type, anything else a plain record.
+ */
+export type PhiCoreWidgetPlacements = {
+    markdown: PhiMarkdownWidgetPlacement;
+    "simple-text": PhiSimpleTextWidgetPlacement;
+    description: PhiDescriptionWidgetPlacement;
+    button: PhiButtonWidgetPlacement;
+    image: PhiImageWidgetPlacement;
+    icon: PhiIconWidgetPlacement;
+    spacer: PhiSpacerWidgetPlacement;
+    html: PhiHtmlWidgetPlacement;
+    table: PhiTableWidgetPlacement;
+    form: PhiFormWidgetPlacement;
+    "collection-view": PhiCollectionViewWidgetPlacement;
+    "command-toolbar": PhiCommandToolbarWidgetPlacement;
+    "theme-mode-switch": PhiThemeModeSwitchWidgetPlacement;
+    "draft-status": PhiDraftStatusWidgetPlacement;
+};
+export type PhiCoreWidgetTypeKey = keyof PhiCoreWidgetPlacements;
+export {};

package/types/core-widget-placements.js

@@ -0,0 +1,3 @@
+// Simple Text
+/** The marks a Simple Text can carry, each on or off. */
+export const PHI_SIMPLE_TEXT_MARKS = ["bold", "italic", "underline", "strike", "code"];

package/types/dashboard-cards.d.ts

@@ -0,0 +1,152 @@
+import type { PhiCmsAreaKey } from "../constants/cms-areas";
+import type { PhiAccessViewer, PhiViewerAccessPolicy } from "./access";
+/**
+ * What a Module offers a Dashboard, and what it is asked for afterwards.
+ *
+ * A Dashboard is a Collection whose items are cards, so nothing here describes a component: a Module
+ * states what its card is called and what it leads to, and Core draws it with the card presentation
+ * every other Collection already uses. See DASHBOARD.md.
+ *
+ * Two shapes, because the list and the payload are two answers. The list is assembled from every active
+ * Module at once and has to be cheap; a payload is one Module doing real work for one card, and it
+ * arrives per card so that twelve of them cost the slowest one rather than the sum.
+ */
+/** `<owner>/cards/<leaf>`: the identity a card keeps across restarts. */
+export type PhiDashboardCardId = `${string}/cards/${string}`;
+export declare function isPhiDashboardCardId(value: unknown): value is PhiDashboardCardId;
+/**
+ * A card's id, written the way every other module-scoped identifier is.
+ *
+ * `cards` joins the closed set of namespaces a package's artifacts live under. A third party invents
+ * Modules and leaves, not namespaces, so this is Core widening the grammar once -- and the reader above
+ * is widened in the same file, because a grammar widened on the writing side alone turns stored data
+ * into rejected data.
+ */
+export declare function createPhiDashboardCardId(moduleId: string, leaf: string): PhiDashboardCardId;
+/**
+ * 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.
+ */
+export type PhiDashboardCardForm = "stat";
+export type PhiDashboardCardDescriptor = {
+    cardId: PhiDashboardCardId;
+    form: PhiDashboardCardForm;
+    /**
+     * What the card says before its payload arrives, already translated.
+     *
+     * A descriptor is assembled on the server, where the label sets are, so a Module answers in the
+     * viewer's language rather than handing Core a key to look up. `title` is what the figure will be
+     * labelled with and it keeps that place afterwards, which is why a card that has not resolved reads
+     * as itself and not as a grey box -- and why one that has resolved still says what it counted.
+     */
+    eyebrow?: string;
+    title: string;
+    description?: string;
+    /**
+     * The small sign beside the title: an icon a preset may name, resolved when it is named.
+     *
+     * `antd:` and a mark the Module ships in its own source qualify. A lookup does not -- `iconify:`
+     * fetches from a third party in the visitor's browser and `asset:` names a file a fresh Site does not
+     * have -- because nobody along the way chose this icon. MODULES.md states the rule; a card
+     * contribution is the case it was written for.
+     */
+    mark?: string;
+    /**
+     * Where the card leads, as the contributing Module's own route preset.
+     *
+     * A preset key rather than a path, so the Dashboard never learns another Module's addresses and a
+     * Site that moved the page keeps a working card. Core resolves it against the Area's active route
+     * table, which means a target the viewer cannot reach simply yields no link.
+     */
+    target?: {
+        ownerModuleId: string;
+        presetKey: string;
+    };
+    /**
+     * Who may see this card at all, when a policy is what decides it.
+     *
+     * The contributing Module answers the question either way: it states a policy here, or it leaves the
+     * card out of its own list. Both are the provider answering, which is the point -- Core never guesses
+     * from the Module's own access policy, because a Module a viewer may enter can still hold a card they
+     * may not see.
+     *
+     * A card the viewer may not see is absent rather than empty: an empty card reports that the thing
+     * exists, and it would reach the loading state to do it.
+     */
+    accessPolicy?: PhiViewerAccessPolicy | null;
+};
+/**
+ * What one card resolved to.
+ *
+ * `error` is a field rather than a thrown request: a payload that fails leaves its own card saying so,
+ * and the other eleven are unaffected. `resolvedAt` is here so a card can be honest about its age,
+ * which is better than every card pretending to be live.
+ */
+export type PhiDashboardCardPayload = {
+    cardId: PhiDashboardCardId;
+    /** The figure, which takes the place the descriptor's title held while it was loading. */
+    value?: string;
+    description?: string;
+    meta?: string;
+    error?: string | null;
+    resolvedAt: string;
+};
+/**
+ * What a Module's card provider is handed.
+ *
+ * The same credentials a feature resolver gets, plus the two things a card decision turns on: which
+ * Area is asking, and who is looking.
+ */
+export type PhiDashboardCardContext = {
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    /**
+     * The request's own cookies, for a card that counts something belonging to the person looking.
+     *
+     * The internal token says which installation is asking, never who. A Core route that answers "my
+     * inbox" resolves the session and refuses without one, so a card about a person needs the credential
+     * that names them -- `viewer` carries what somebody may reach, which is a different question from
+     * who they are.
+     *
+     * It is not a widening of what a provider holds. `internalToken` is already here, and it is the
+     * service credential: strictly more than one person's session.
+     */
+    cookieHeader: string;
+    locale: string;
+    area: PhiCmsAreaKey;
+    viewer: PhiAccessViewer;
+};
+/**
+ * One Module's answer, loaded on the server and never reached from the browser.
+ *
+ * `listCards` is asked once per Dashboard request for every active Module; `resolveCard` is asked once
+ * per card, by the card. A Module that contributes nothing to this Area answers with an empty list,
+ * which is cheaper than Core deciding on its behalf.
+ */
+export type PhiDashboardCardProvider = {
+    listCards: (context: PhiDashboardCardContext) => Promise<readonly PhiDashboardCardDescriptor[]> | readonly PhiDashboardCardDescriptor[];
+    resolveCard: (cardId: PhiDashboardCardId, context: PhiDashboardCardContext) => Promise<PhiDashboardCardPayload> | PhiDashboardCardPayload;
+};
+/**
+ * What the Dashboard's fan-in provider answers with, and what its card View reads.
+ *
+ * One row per card, because a Collection has rows. The descriptor's fields are flattened onto it so the
+ * shared card presentation can point at them by path like any other resource -- `href` included, which
+ * Core resolved from the target so the row carries an address rather than a preset key the browser
+ * would have to look up.
+ */
+export type PhiDashboardCardRow = {
+    cardId: PhiDashboardCardId;
+    form: PhiDashboardCardForm;
+    eyebrow?: string;
+    title: string;
+    description?: string;
+    mark?: string;
+    href?: string;
+};

package/types/dashboard-cards.js

@@ -0,0 +1,15 @@
+import { createPhiModuleIdentifier, isPhiModuleScopedIdentifier } from "../constants/module-identity";
+export function isPhiDashboardCardId(value) {
+    return isPhiModuleScopedIdentifier("cards", value);
+}
+/**
+ * A card's id, written the way every other module-scoped identifier is.
+ *
+ * `cards` joins the closed set of namespaces a package's artifacts live under. A third party invents
+ * Modules and leaves, not namespaces, so this is Core widening the grammar once -- and the reader above
+ * is widened in the same file, because a grammar widened on the writing side alone turns stored data
+ * into rejected data.
+ */
+export function createPhiDashboardCardId(moduleId, leaf) {
+    return createPhiModuleIdentifier(moduleId, "cards", leaf, "segment");
+}

package/types/draft-status.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a Controller says about the draft it holds, on the `draftStatus` channel.
+ *
+ * The value of `PHI_SIGNAL_VALUE_SCHEMAS.revisionsDraftStatus`. Whoever keeps a draft -- the Builder's
+ * workspaces, the Theme, a Module's own -- states it in these words, and the Core Draft Status Widget
+ * draws them without knowing what the draft is of:
+ *
+ * - `unsaved`: worked on since the last save; what is on screen is in no stored revision.
+ * - `draft`: saved, not published; `revisionId` names the draft revision.
+ * - `published`: no draft stands; what is live is what is shown.
+ * - `error`: the state could not be read; `error` says why when the sender knows.
+ *
+ * `subject` is the sender's own name for what the draft is of -- a path, a key -- shown beside the
+ * status. Senders may add fields of their own; a reader takes these and ignores the rest.
+ */
+export type PhiDraftStatus = "unsaved" | "draft" | "published" | "error";
+export type PhiDraftStatusSignalValue = {
+    status: PhiDraftStatus;
+    revisionId: number | null;
+    subject?: string | null;
+    error?: string | null;
+};
+export declare function readPhiDraftStatusSignalValue(value: unknown): PhiDraftStatusSignalValue | null;