@phis/ui 0.1.0 → 0.2.1

package/plugins/runtime-modules/news/module.d.ts

@@ -0,0 +1,157 @@
+/**
+ * No Controller: nothing here coordinates between surfaces.
+ *
+ * The Table announces which action happened on which row, and each dialog and each Form decides by its
+ * own `openActionKey` whether it was meant; a Form that went through closes its dialog and tells the
+ * Table to read again. A Controller would be a place for state none of them keeps -- it held two things,
+ * a spinner on the Save button and a refusal to close mid-save, and cost three silent failures for them.
+ */
+export declare const PHI_NEWS_RUNTIME_MODULE: {
+    moduleId: "@phis/ui/modules/news";
+    kind: "module";
+    eligibleAreas: readonly ["public", "editor"];
+    serverBinding: import("../../../types").PhiRuntimeModuleServerBinding;
+    title: string;
+    description: string;
+    category: "content";
+    icon: string;
+    dataProviders: ({
+        key: `${string}/${string}`;
+        ownerModuleId: "@phis/ui/modules/news";
+        kind: "table";
+        executionMode: "live";
+        authoringMode: "none";
+        title: string;
+        description: string;
+        resources: {
+            resourceKey: string;
+            title: string;
+            rowIdentityPath: string;
+            fields: ({
+                key: string;
+                title: string;
+                type: "number";
+                required: true;
+                options?: undefined;
+                mutable?: undefined;
+                optionsProvider?: undefined;
+            } | {
+                key: string;
+                title: string;
+                type: "string";
+                required: true;
+                options?: undefined;
+                mutable?: undefined;
+                optionsProvider?: undefined;
+            } | {
+                key: string;
+                title: string;
+                type: "string";
+                required?: undefined;
+                options?: undefined;
+                mutable?: undefined;
+                optionsProvider?: undefined;
+            } | {
+                key: string;
+                title: string;
+                type: "enum";
+                options: {
+                    value: string;
+                    label: string;
+                }[];
+                required?: undefined;
+                mutable?: undefined;
+                optionsProvider?: undefined;
+            } | {
+                key: string;
+                title: string;
+                type: "boolean";
+                required?: undefined;
+                options?: undefined;
+                mutable?: undefined;
+                optionsProvider?: undefined;
+            } | {
+                key: string;
+                title: string;
+                type: "enum[]";
+                mutable: true;
+                optionsProvider: {
+                    providerKey: `${string}/${string}`;
+                };
+                required?: undefined;
+                options?: undefined;
+            } | {
+                key: string;
+                title: string;
+                type: "datetime";
+                required?: undefined;
+                options?: undefined;
+                mutable?: undefined;
+                optionsProvider?: undefined;
+            })[];
+            query: {
+                search: true;
+                filterFields: string[];
+                sorting: "none";
+                pagination: "offset";
+                facets: string[];
+            };
+            recordRead: true;
+            actions: ({
+                key: string;
+                title: string;
+                scope: "row";
+                disabledWhen: {
+                    match: "any";
+                    conditions: {
+                        source: "row";
+                        valuePath: string;
+                        operator: "falsy";
+                    }[];
+                };
+                confirmation: "required";
+                intent?: undefined;
+            } | {
+                key: string;
+                title: string;
+                scope: "row";
+                intent: "destructive";
+                confirmation: "required";
+                disabledWhen?: undefined;
+            } | {
+                key: string;
+                title: string;
+                scope: "resource";
+                disabledWhen?: undefined;
+                confirmation?: undefined;
+                intent?: undefined;
+            })[];
+        }[];
+    } | {
+        key: `${string}/${string}`;
+        ownerModuleId: "@phis/ui/modules/news";
+        kind: "options";
+        executionMode: "live";
+        authoringMode: "none";
+        title: string;
+        description: string;
+        resources?: undefined;
+    })[];
+    formProviders: {
+        handlers: {
+            key: `${string}/${string}`;
+            ownerModuleId: "@phis/ui/modules/news";
+            title: string;
+            phase: "submit";
+            handlerKey: "news.entry" | "news.publication";
+            category: "forms";
+            transport: "relay";
+            method: "POST" | "PUT";
+            endpointKey: null;
+            upstreamPath: string;
+            csrfPath: null;
+            requiresCsrf: false;
+            credentialPolicy: "site-session";
+        }[];
+    };
+};

package/plugins/runtime-modules/news/module.js

@@ -0,0 +1,12 @@
+import { PHI_NEWS_RUNTIME_MODULE_DEFINITION } from "./definition";
+/**
+ * No Controller: nothing here coordinates between surfaces.
+ *
+ * The Table announces which action happened on which row, and each dialog and each Form decides by its
+ * own `openActionKey` whether it was meant; a Form that went through closes its dialog and tells the
+ * Table to read again. A Controller would be a place for state none of them keeps -- it held two things,
+ * a spinner on the Save button and a refusal to close mid-save, and cost three silent failures for them.
+ */
+export const PHI_NEWS_RUNTIME_MODULE = {
+    ...PHI_NEWS_RUNTIME_MODULE_DEFINITION,
+};

package/plugins/runtime-modules/news/presets.d.ts

@@ -0,0 +1,17 @@
+import type { PhiCmsRoutePresetDescriptor } from "../../../types/cms-module-descriptors";
+/**
+ * One address, and the header entry that leads to it.
+ *
+ * Nothing is seeded: the entry is computed per request from the compiled catalog once the Module is active
+ * for the Area, the same way `/register` gets its own. A Site may rename, reorder or tombstone it through
+ * the navigation overlay, and may not hide it -- which is the rule that keeps a Module's address
+ * reachable.
+ *
+ * No `/news/<slug>` in this version. A whole-segment parameter is permitted
+ * ([MODULES.md](../../../MODULES.md)) and the slug is already on the row, so a detail address later costs
+ * a descriptor and no change to any data.
+ *
+ * Indexable, unlike the auth Pages beside it: a Site's news is exactly the kind of page a search engine
+ * should find, so no `NoIndex` flag is set.
+ */
+export declare const PHI_NEWS_RUNTIME_MODULE_ROUTES: PhiCmsRoutePresetDescriptor[];

package/plugins/runtime-modules/news/presets.js

@@ -0,0 +1,64 @@
+import { buildPhiSidebarRoutePresetDescriptor } from "../sidebar-route";
+import { PHI_EDITOR_NEWS_PAGE_PRESET_KEY, PHI_NEWS_RUNTIME_MODULE_ID } from "./ids";
+const PHI_NEWS_PAGE_PRESET_KEY = "public-news-page";
+/**
+ * One address, and the header entry that leads to it.
+ *
+ * Nothing is seeded: the entry is computed per request from the compiled catalog once the Module is active
+ * for the Area, the same way `/register` gets its own. A Site may rename, reorder or tombstone it through
+ * the navigation overlay, and may not hide it -- which is the rule that keeps a Module's address
+ * reachable.
+ *
+ * No `/news/<slug>` in this version. A whole-segment parameter is permitted
+ * ([MODULES.md](../../../MODULES.md)) and the slug is already on the row, so a detail address later costs
+ * a descriptor and no change to any data.
+ *
+ * Indexable, unlike the auth Pages beside it: a Site's news is exactly the kind of page a search engine
+ * should find, so no `NoIndex` flag is set.
+ */
+export const PHI_NEWS_RUNTIME_MODULE_ROUTES = [
+    {
+        ownerModuleId: PHI_NEWS_RUNTIME_MODULE_ID,
+        presetKey: PHI_NEWS_PAGE_PRESET_KEY,
+        presetVersion: 1,
+        area: "public",
+        title: "News",
+        path: "/news",
+        navigation: [{
+                // Unanchored: the Public header exports no base item, so the entry lands at the end of the surface.
+                navKey: "public:header",
+                parentItemKey: null,
+                item: {
+                    itemKey: "@phis/ui/modules/news/nav/public/news",
+                    label: { defaultMessage: "News" },
+                    icon: "antd:notification",
+                    routePresetKey: PHI_NEWS_PAGE_PRESET_KEY,
+                },
+            }],
+        loadTree: ({ page }) => import("./trees/phi-default-pub-news-page-tree")
+            .then((module) => module.buildPhiDefaultPubNewsPageTree({ page })),
+    },
+    /*
+     * Where the entries are written, contributed by this Module rather than by the Area.
+     *
+     * The Page, its address, its name in the sidebar and the Table's own logic are all this Module's, which
+     * is what a Module is: switch it off and the Page and its entry go with it, because both are computed
+     * per request from the compiled catalog. Nothing of it sits in the Editor Area's own definition, so a
+     * Module outside this package contributes an editing surface exactly the same way.
+     *
+     * `anchor: "main"` rather than a parent item key: the sidebar exports roles, not items, and naming
+     * another Module's entry would make this one depend on it being there.
+     */
+    buildPhiSidebarRoutePresetDescriptor({
+        area: "editor",
+        anchor: "main",
+        ownerModuleId: PHI_NEWS_RUNTIME_MODULE_ID,
+        presetKey: PHI_EDITOR_NEWS_PAGE_PRESET_KEY,
+        title: "News",
+        path: "/news",
+        itemKey: "@phis/ui/modules/news/nav/editor/news",
+        icon: "antd:notification",
+        loadTree: ({ page, runtime }) => import("./trees/phi-default-editor-news-page-tree")
+            .then((module) => module.buildPhiDefaultEditorNewsPageTree({ page, runtime })),
+    }),
+];

package/plugins/runtime-modules/news/server.d.ts

@@ -0,0 +1 @@
+export declare function createPhiNewsRuntimeModuleServerAreaContribution(): import("../area-contributions").PhiRuntimeModuleServerAreaContribution;

package/plugins/runtime-modules/news/server.js

@@ -0,0 +1,18 @@
+import { definePhiRuntimeModuleServerAreaContribution } from "../area-contributions";
+import { PHI_NEWS_RUNTIME_MODULE_DEFINITION } from "./definition";
+import { PHI_NEWS_RUNTIME_MODULE_FORMS } from "./forms";
+import { PHI_NEWS_RUNTIME_MODULE_ROUTES } from "./presets";
+import { PHI_NEWS_RUNTIME_MODULE_WIDGETS } from "./widgets";
+export function createPhiNewsRuntimeModuleServerAreaContribution() {
+    return definePhiRuntimeModuleServerAreaContribution({
+        moduleId: PHI_NEWS_RUNTIME_MODULE_DEFINITION.moduleId,
+        catalogEntry: {
+            definition: PHI_NEWS_RUNTIME_MODULE_DEFINITION,
+            widgets: PHI_NEWS_RUNTIME_MODULE_WIDGETS,
+            layouts: [],
+            forms: PHI_NEWS_RUNTIME_MODULE_FORMS,
+            routes: PHI_NEWS_RUNTIME_MODULE_ROUTES,
+            load: () => import("./module").then((module) => module.PHI_NEWS_RUNTIME_MODULE),
+        },
+    });
+}

package/plugins/runtime-modules/news/services/options.d.ts

@@ -0,0 +1,3 @@
+export declare const PhiNewsTagsOptionsProviderClient: import("react").ComponentType<{
+    children: import("react").ReactNode;
+}>;

package/plugins/runtime-modules/news/services/options.js

@@ -0,0 +1,35 @@
+"use client";
+import { createPhiControlOptionsProviderClient, } from "../../../../components/controls/phi-options-provider";
+import { PHI_NEWS_RUNTIME_DATA_PROVIDER_KEYS } from "../ids";
+/**
+ * The tags this Site's entries already carry, which is the offer a tag field picks from.
+ *
+ * There is no vocabulary behind it: a tag is a string on an entry, so the offer is the set of them and a
+ * tag nobody carries any more leaves it by itself. Answered by the same endpoint that lists the entries --
+ * it is the same question -- with one row asked for, because only the facet is wanted here.
+ *
+ * Picked rather than typed is the whole point. Two spellings would be two tags with two translations to
+ * pay for, and the store lower-cases what it is given precisely so that this list stays short.
+ */
+const NEWS_API_PATH = "/api/site/editor/news?page=1&pageSize=1";
+export const PhiNewsTagsOptionsProviderClient = createPhiControlOptionsProviderClient({
+    key: PHI_NEWS_RUNTIME_DATA_PROVIDER_KEYS.tags,
+    load: async () => {
+        const response = await fetch(NEWS_API_PATH, {
+            cache: "no-store",
+            credentials: "include",
+            headers: { accept: "application/json" },
+        });
+        const payload = await response.json().catch(() => null);
+        if (!response.ok)
+            throw new Error("Failed to load the tags in use.");
+        return payload;
+    },
+    resolveLoadKey: () => "news-tags",
+    resolve: (context) => {
+        const tags = context.asyncData?.tags;
+        return {
+            options: (Array.isArray(tags) ? tags : []).flatMap((tag) => typeof tag === "string" && tag.trim() ? [{ value: tag, label: tag }] : []),
+        };
+    },
+});

package/plugins/runtime-modules/news/services/table.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+/**
+ * The Site's News entries for a Table, and the two things an entry can have done to it without a Form.
+ *
+ * Withdrawing and deleting state nothing -- no words, no dates -- so they are actions here rather than
+ * Forms. Saving and publishing do state something, and they are Forms elsewhere on the page.
+ *
+ * A refusal keeps its reason: Core answers `409` with a sentence when a published entry is to be deleted,
+ * and that sentence is what the Table shows. Disabling the action in the row as well would be a second
+ * answer to the same question, drawn from a row that may be a minute old.
+ */
+export declare function PhiNewsTableProviderClient({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/plugins/runtime-modules/news/services/table.js

@@ -0,0 +1,144 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef } from "react";
+import { isPhiRecord } from "../../../../helpers/is-record";
+import { PhiTableProviderError, } from "../../../../types/table-widget";
+import { PhiTableProviderClient, } from "../../../../components/widgets/client/shared/phi-table-provider";
+import { readPhiTableProviderResponse, } from "../../../../components/widgets/client/shared/phi-table-provider-response";
+import { PHI_NEWS_RUNTIME_DATA_PROVIDER_DESCRIPTORS } from "../data-providers";
+import { PHI_NEWS_RUNTIME_DATA_PROVIDER_KEYS, PHI_NEWS_TABLE_RESOURCE_KEY } from "../ids";
+/** The editor's own endpoints, behind the content-editing guard and the publishing one. */
+const NEWS_API_PATH = "/api/site/editor/news";
+const NEWS_PUBLISH_API_PATH = "/api/site/editor/news/publish";
+const RESPONSE_OPTIONS = { subject: "News" };
+function readNumber(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+/**
+ * The store's status as the Table speaks it.
+ *
+ * `0` and `1` are `DB.md`'s vocabulary and stay in the store; a Table draws a badge, which needs a word,
+ * and the status filter already sends one. Anything the release does not know keeps its number rather than
+ * being read as a draft -- a status nobody recognises must not look like the least published one.
+ */
+function readStatusWord(status) {
+    if (status === 0)
+        return "draft";
+    if (status === 1)
+        return "published";
+    return String(status ?? "");
+}
+function readStringFilter(query, key) {
+    const value = query.filters?.[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function buildQueryParams(query) {
+    const params = new URLSearchParams({
+        page: String(query.page && query.page > 0 ? query.page : 1),
+        pageSize: String(query.pageSize && query.pageSize > 0 ? query.pageSize : 25),
+    });
+    const search = query.search?.trim() ?? "";
+    if (search)
+        params.set("search", search);
+    const status = readStringFilter(query, "status");
+    // "all" is the Table's way of saying no filter, and the endpoint reads anything it does not know as none.
+    if (status && status !== "all")
+        params.set("status", status);
+    return params;
+}
+async function loadEntries({ query, signal, }) {
+    const result = await readPhiTableProviderResponse(await fetch(`${NEWS_API_PATH}?${buildQueryParams(query).toString()}`, {
+        cache: "no-store",
+        credentials: "include",
+        headers: { accept: "application/json" },
+        signal,
+    }), RESPONSE_OPTIONS);
+    const rows = (Array.isArray(result?.entries) ? result.entries.filter(isPhiRecord) : [])
+        .map((row) => ({ ...row, status: readStatusWord(row.status) }));
+    return {
+        rows,
+        total: readNumber(result?.total, rows.length),
+        page: readNumber(result?.page, 1),
+        pageSize: readNumber(result?.pageSize, rows.length || 25),
+        /*
+         * The tags the Site already uses, answered beside the page. It is a facet rather than a second request
+         * because it is the same question: what is in these entries.
+         */
+        facets: { tags: Array.isArray(result?.tags) ? result.tags : [] },
+    };
+}
+/**
+ * The Site's News entries for a Table, and the two things an entry can have done to it without a Form.
+ *
+ * Withdrawing and deleting state nothing -- no words, no dates -- so they are actions here rather than
+ * Forms. Saving and publishing do state something, and they are Forms elsewhere on the page.
+ *
+ * A refusal keeps its reason: Core answers `409` with a sentence when a published entry is to be deleted,
+ * and that sentence is what the Table shows. Disabling the action in the row as well would be a second
+ * answer to the same question, drawn from a row that may be a minute old.
+ */
+export function PhiNewsTableProviderClient({ children }) {
+    const recordsRef = useRef(new Map());
+    const query = useCallback(async (request) => {
+        if (request.resourceKey !== PHI_NEWS_TABLE_RESOURCE_KEY) {
+            throw new PhiTableProviderError("resource-not-found", `Unknown News resource "${request.resourceKey}".`);
+        }
+        const data = await loadEntries(request);
+        for (const row of data.rows) {
+            recordsRef.current.set(String(row.contentId), row);
+        }
+        return data;
+    }, []);
+    const readRecord = useCallback(async ({ rowIdentity, }) => {
+        if (rowIdentity == null) {
+            throw new PhiTableProviderError("record-identity-required", "A news entry identity is required.");
+        }
+        const record = recordsRef.current.get(String(rowIdentity));
+        if (!record) {
+            throw new PhiTableProviderError("record-not-loaded", "That news entry is no longer in the current Table view. Reload the Table and try again.");
+        }
+        return record;
+    }, []);
+    const mutate = useCallback(async (request) => {
+        if (request.kind !== "action") {
+            throw new PhiTableProviderError("mutation-not-supported", "News rows are edited through the Form.");
+        }
+        if (request.actionKey === "refresh") {
+            return { status: "accepted", invalidation: "view" };
+        }
+        const contentId = Number(request.rowIdentity);
+        if (!Number.isInteger(contentId) || contentId <= 0) {
+            throw new PhiTableProviderError("invalid-row-identity", "That action needs a news entry.");
+        }
+        const params = new URLSearchParams({ contentId: String(contentId) });
+        const path = request.actionKey === "withdraw"
+            ? NEWS_PUBLISH_API_PATH
+            : request.actionKey === "delete"
+                ? NEWS_API_PATH
+                : null;
+        if (!path) {
+            throw new PhiTableProviderError("action-not-supported", `Unsupported News action "${request.actionKey}".`);
+        }
+        await readPhiTableProviderResponse(await fetch(`${path}?${params.toString()}`, {
+            method: "DELETE",
+            cache: "no-store",
+            credentials: "include",
+            headers: { accept: "application/json" },
+            signal: request.signal,
+        }), RESPONSE_OPTIONS);
+        /*
+         * `resource` rather than `view`: withdrawing changes the status and the dates, deleting removes the row,
+         * and both change what the tag facet answers. Re-reading the page is cheaper than reasoning about which
+         * parts of it are still true.
+         */
+        return { status: "accepted", invalidation: "resource" };
+    }, []);
+    const registration = useMemo(() => ({
+        key: PHI_NEWS_RUNTIME_DATA_PROVIDER_KEYS.table,
+        resources: PHI_NEWS_RUNTIME_DATA_PROVIDER_DESCRIPTORS.find((descriptor) => descriptor.key === PHI_NEWS_RUNTIME_DATA_PROVIDER_KEYS.table)?.resources ?? [],
+        query,
+        readRecord,
+        mutate,
+    }), [mutate, query, readRecord]);
+    return _jsx(PhiTableProviderClient, { registration: registration, children: children });
+}

package/plugins/runtime-modules/news/trees/editor-news-label-set.d.ts

@@ -0,0 +1,8 @@
+import "server-only";
+import { type PhiGlobalTranslatorOptions } from "../../../../gateway/tr";
+export declare function getPhiEditorNewsPageLabels(options: PhiGlobalTranslatorOptions): Promise<{
+    pageTitle: string;
+    pageDescription: string;
+    contentLabel: string;
+    widgetLabel: string;
+}>;

package/plugins/runtime-modules/news/trees/editor-news-label-set.js

@@ -0,0 +1,29 @@
+import "server-only";
+import { PHI_TR_CTX_WEB_UI_LABEL } from "../../../../gateway/tr";
+import { definePhiLabelSet, definePhiMessageLabel, getPhiLabelSet } from "../../../../gateway/label-set";
+/**
+ * What the News page in the Editor says about itself.
+ *
+ * The page's own frame only. What the Table says -- its columns, its filters, its refusals -- is the
+ * Widget's label set, because those words belong to the Table wherever a Site places it and not to this
+ * one Page.
+ */
+const PHI_EDITOR_NEWS_PAGE_LABEL_SET = definePhiLabelSet({
+    key: "preset:editor-news-page",
+    ctx: PHI_TR_CTX_WEB_UI_LABEL,
+    labels: {
+        page_title: "News",
+        page_description: definePhiMessageLabel("The Site's news entries. What a visitor reads is whatever is published and has not expired."),
+        content_label: "news",
+        widget_label: "news entries",
+    },
+});
+export async function getPhiEditorNewsPageLabels(options) {
+    const labels = await getPhiLabelSet(options, PHI_EDITOR_NEWS_PAGE_LABEL_SET);
+    return {
+        pageTitle: labels.page_title,
+        pageDescription: labels.page_description,
+        contentLabel: labels.content_label,
+        widgetLabel: labels.widget_label,
+    };
+}

package/plugins/runtime-modules/news/trees/editor-news-widget-label-set.d.ts

@@ -0,0 +1,65 @@
+import "server-only";
+import { type PhiGlobalTranslatorOptions } from "../../../../gateway/tr";
+export type PhiEditorNewsWidgetLabels = {
+    searchPlaceholder: string;
+    statusLabel: string;
+    statuses: {
+        all: string;
+        draft: string;
+        published: string;
+    };
+    rowStatus: {
+        draft: string;
+        published: string;
+    };
+    columns: {
+        title: string;
+        slug: string;
+        status: string;
+        language: string;
+        tags: string;
+        published: string;
+        expires: string;
+        changed: string;
+    };
+    actions: {
+        withdraw: string;
+        delete: string;
+        new: string;
+        edit: string;
+        publish: string;
+    };
+    overlays: {
+        create: string;
+        entry: string;
+        publication: string;
+    };
+    form: {
+        save: string;
+        cancel: string;
+        slugPlaceholder: string;
+        slugError: string;
+        titleError: string;
+        subtitleLabel: string;
+        contentLabel: string;
+        contentPlaceholder: string;
+        contentError: string;
+        linkLabel: string;
+        linkPlaceholder: string;
+        sourceLocalePlaceholder: string;
+        translateLabel: string;
+    };
+    withdraw: {
+        title: string;
+        description: string;
+    };
+    delete: {
+        title: string;
+        description: string;
+    };
+    empty: {
+        title: string;
+        text: string;
+    };
+};
+export declare function getPhiEditorNewsWidgetLabels(options: PhiGlobalTranslatorOptions): Promise<PhiEditorNewsWidgetLabels>;