@webx-ui/module-pages 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webx-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @webx-ui/module-pages
+
+The front end of the pages section of the [WebX UI](https://github.com/webx-ui/webx-ui) admin
+panel: the site's pages as a tree, their addresses, and the dialogs that create and move them.
+
+The other half is the Composer package `webx-ui/module-pages`, which owns the tree, the
+addresses and the API. A section appears in the panel when both halves are installed.
+
+## Install
+
+```bash
+npm install @webx-ui/module-pages
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { pages } from '@webx-ui/module-pages'
+import '@webx-ui/module-pages/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [pages()],
+}).mount()
+```
+
+`pages({ path: '/content' })` puts the section somewhere else inside the panel.
+
+## The list
+
+One level of the tree at a time. The home page is pinned at the top and its children are the
+level below it: every page of the site is inside the home page, so drawing it as a branch would
+give every row a step of indentation that says nothing.
+
+- **Children arrive when a branch is opened** — a catalogue of a few hundred pages is never
+  fetched whole.
+- **Searching puts the tree away** and answers with a flat list of matches, each with its
+  address: a branch drawn for the sake of one match deep inside it tells the reader nothing.
+- **The bin is a filter, not a section.** It lists the pages somebody deleted; whatever went
+  down with a page comes back with it.
+- **Two ways to move a page:** drag it, or use “Move…” and pick the page it goes inside —
+  which is the one that works on a touch screen and in a big catalogue.
+
+Moving a page rewrites every address under it and leaves a redirect on each of the old ones,
+and the section says so out loud: an editor should not learn about a thousand redirects from a
+search engine.
+
+## The API
+
+`createPagesApi(context)` is the same set of calls the screen makes, for a panel that wants to
+do something else with them:
+
+```ts
+const api = createPagesApi(useAdmin())
+
+await api.list({ parent: 12 })
+await api.create({ title: 'About us', parent_id: 1 })
+await api.move(12, 1, 'inside')
+await api.remove(12) // to the bin, with the branch under it
+```
+
+## Licence
+
+MIT

package/dist/PageActions.d.ts

@@ -0,0 +1,36 @@
+import { PageRow } from './types';
+/**
+ * What a row offers, in a table cell or on a card.
+ *
+ * Written once as a list and drawn twice: a row is read by shape, a menu is read by name, and
+ * seven unlabelled icons in a dropdown would be worse than the row they replaced. On a card
+ * there is no row at all — at that width the card is the screen, and a menu of words is easier
+ * to hit than seven targets the size of a fingernail.
+ */
+type __VLS_Props = {
+    page: PageRow;
+    inBin?: boolean;
+    /** Only the menu, for a card. */
+    menuOnly?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    open: (page: PageRow) => any;
+    duplicate: (page: PageRow) => any;
+    move: (page: PageRow) => any;
+    restore: (page: PageRow) => any;
+    remove: (page: PageRow) => any;
+    add: (page: PageRow) => any;
+    copy: (page: PageRow) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onOpen?: ((page: PageRow) => any) | undefined;
+    onDuplicate?: ((page: PageRow) => any) | undefined;
+    onMove?: ((page: PageRow) => any) | undefined;
+    onRestore?: ((page: PageRow) => any) | undefined;
+    onRemove?: ((page: PageRow) => any) | undefined;
+    onAdd?: ((page: PageRow) => any) | undefined;
+    onCopy?: ((page: PageRow) => any) | undefined;
+}>, {
+    inBin: boolean;
+    menuOnly: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/PageCreateDialog.d.ts

@@ -0,0 +1,16 @@
+import { PageRow } from './types';
+/**
+ * A new page: what it is called, where it lives, and what it is called in the address.
+ *
+ * The address follows the title while nobody has touched it, and stops the moment somebody
+ * does — a field that keeps rewriting what was typed into it is a field people fight.
+ */
+type __VLS_Props = {
+    parent?: PageRow | null;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    parent: PageRow | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    field: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/PageDanger.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/PageEditorPage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The editor of one page: a head that stays put, and the described screen under it.
+ *
+ * What the page itself owns is the head — where this page sits, what state it is in, and the
+ * three things that change that state — and the saving. Everything below the head is
+ * `pages.form`, so a module or a project adds a tab to the editor with a patch (§12) rather
+ * than with a fork of this file.
+ *
+ * Saving is by autosave: a pause after the last keystroke, and the moment a field is left. The
+ * explicit button is still there, because a button that says "saved" is the only way a person
+ * can be sure — but nothing is ever lost by not pressing it.
+ */
+type __VLS_Props = {
+    base?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    base: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    root: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/PageHistory.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLDivElement>;
+export default _default;

package/dist/PageMoveDialog.d.ts

@@ -0,0 +1,15 @@
+import { PageRow } from './types';
+/**
+ * Where a page goes, chosen from a tree rather than dragged.
+ *
+ * Dragging is the quick way and it is in the table already; this is the one that works — on a
+ * touch screen, and in a catalogue where the page and its new parent are four screens apart.
+ *
+ * Inside, and only inside. Order among siblings is what dragging is for, and a dialog that also
+ * asked "before or after what" would be asking about the one thing nobody opened it for.
+ */
+type __VLS_Props = {
+    page: PageRow;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/PagePicker.d.ts

@@ -0,0 +1,28 @@
+import { PageRow } from './types';
+/**
+ * A page chosen out of the tree — where a new page goes, or where a moved one lands.
+ *
+ * Lazy, like the section's own list: a catalogue is fetched a level at a time, and a picker
+ * that pulled the whole tree down to offer one parent would be the one screen of the section
+ * that does not.
+ */
+type __VLS_Props = {
+    /** Pages that may not be chosen — the page being moved, above all. */
+    exclude?: number[];
+    placeholder?: string;
+    /** The page the value names, with its ancestors, so a lazy tree can show it unopened. */
+    selected?: PageRow[];
+};
+type __VLS_PublicProps = {
+    modelValue?: number | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: number | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: number | null) => any) | undefined;
+}>, {
+    placeholder: string;
+    exclude: number[];
+    selected: PageRow[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/PagePlace.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/PagesPage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The section: the site's pages as a tree, a level at a time.
+ *
+ * The home page is pinned at the top and its children are the top level, because every page of
+ * the site is inside it — drawn as a branch, every row of the table would carry one step of
+ * indentation that says nothing (§9).
+ *
+ * Searching puts the tree away. A branch drawn for the sake of one match deep inside it tells
+ * the reader nothing they asked about, so a search is a flat list of matches with the address
+ * under each.
+ */
+type __VLS_Props = {
+    base?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    base: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    root: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,34 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { PageDetail, PageDropZone, PageInput, PageLevel, PageMoveResult, PageRow, PageSave, PageVersion } from './types';
+export interface PagesApi {
+    /** One level of the tree, or a flat list when searching or looking in the bin. */
+    list(query?: {
+        parent?: number | null;
+        search?: string;
+        status?: string;
+        trashed?: boolean;
+        /** The whole tree in one flat list, in the order it reads top to bottom. */
+        flat?: boolean;
+    }): Promise<PageLevel>;
+    get(id: number): Promise<PageDetail>;
+    create(input: PageInput): Promise<PageRow>;
+    /**
+     * Save the draft. Refused with a 409 when the revision is not the current one — the error's
+     * body is a {@link PageConflict}, and the page it carries is the page as it now is.
+     */
+    save(id: number, input: PageSave): Promise<PageDetail>;
+    move(id: number, target: number, zone: PageDropZone): Promise<PageMoveResult>;
+    duplicate(id: number): Promise<PageRow>;
+    publish(id: number): Promise<PageRow>;
+    unpublish(id: number): Promise<PageRow>;
+    /** Into the bin, with the branch under it. Answers how many went. */
+    remove(id: number): Promise<number>;
+    /** Out of the bin, with whatever went in with it. Answers how many came back. */
+    restore(id: number): Promise<number>;
+    /** The publications, newest first. */
+    versions(id: number): Promise<PageVersion[]>;
+    /** An old publication becomes the draft; putting it on the site is a separate step. */
+    restoreVersion(id: number, number: number): Promise<PageDetail>;
+}
+/** Everything under `/pages`, below the panel's API path. */
+export declare function createPagesApi(admin: AdminContext): PagesApi;

package/dist/editor.d.ts

@@ -0,0 +1,43 @@
+import { InjectionKey, Ref } from 'vue';
+import { ScreenModel } from '@webx-ui/schema';
+import { PageRow } from './types';
+/**
+ * What the editor knows and the nodes of its screen do not.
+ *
+ * The form is a described screen (`pages.form`), so the parts of it that are not fields —
+ * where the page sits, what may be done to it, what its history is — arrive as node types of
+ * their own. Each of those needs the page being edited, and none of them can be handed it
+ * through the description: a screen is a description, not a binding. So the page that hosts
+ * the screen provides it, the same way it provides the preview to `wx-blocks`.
+ */
+export interface PageEditorContext {
+    /** The page as the server last answered it, or `null` while the first request is in flight. */
+    page: Ref<PageRow | null>;
+    /** The trail above it, home page first. */
+    ancestors: Ref<PageRow[]>;
+    /**
+     * The values of the screen as they are right now, edits included.
+     *
+     * A node that only draws still has to follow what is being typed: the address is a sentence
+     * made of the slug field, and one that updated on save would be showing the old address at
+     * the moment the new one is most worth reading.
+     */
+    values: Ref<ScreenModel>;
+    /** The address of the page above, by content language. */
+    prefixes: Ref<Record<string, string>>;
+    /** Where the section lives, for the links the nodes draw. */
+    base: string;
+    /** Whether this administrator may write at all. */
+    canManage: boolean;
+    /** Ask the server for the page again — after a move, a restore, a publication. */
+    reload(): Promise<void>;
+    /** Write the draft now rather than at the end of the next pause. */
+    save(): Promise<void>;
+}
+export declare const pageEditorKey: InjectionKey<PageEditorContext>;
+export declare function providePageEditor(editor: PageEditorContext): void;
+/**
+ * The editor above this node, or `null` outside one — a node of `pages.form` drawn in a demo
+ * or a test has no page to talk about, and must draw nothing rather than throw.
+ */
+export declare function usePageEditor(): PageEditorContext | null;

package/dist/i18n.d.ts

@@ -0,0 +1,2 @@
+/** Puts this package's English under the panel's dictionary, once per panel. */
+export declare function usePagesMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { pages, type PagesOptions } from './module';
+export { createPagesApi, type PagesApi } from './api';
+export { pageEditorKey, providePageEditor, usePageEditor, type PageEditorContext } from './editor';
+export { pagesMessages } from './messages';
+export { slugify } from './slug';
+export { default as WxPagesPage } from './PagesPage';
+export { default as WxPageEditorPage } from './PageEditorPage';
+export { default as WxPagePicker } from './PagePicker';
+export { default as WxPagePlace } from './PagePlace';
+export { default as WxPageDanger } from './PageDanger';
+export { default as WxPageHistory } from './PageHistory';
+export type { PageCapabilities, PageConflict, PageDetail, PageDropZone, PageInput, PageLevel, PageMoveResult, PageQuery, PageRow, PageSave, PageStatus, PageVersion, } from './types';