@webx-ui/module-blog 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,50 @@
+# @webx-ui/module-blog
+
+The front end of the blog section of the [WebX UI](https://github.com/webx-ui/webx-ui) admin
+panel: articles, and — as they are written — rubrics and tags.
+
+The other half is the Composer package `webx-ui/module-blog`, which owns the articles, their
+addresses, their publication dates and the API. A section appears in the panel when both halves
+are installed.
+
+## Install
+
+```bash
+npm install @webx-ui/module-blog
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { blog } from '@webx-ui/module-blog'
+import '@webx-ui/module-blog/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [...blog()],
+}).mount()
+```
+
+`blog()` answers with a section per entry of the navigation rather than with one module, because
+the panel draws one entry per module and the blog wants three — articles, rubrics and tags,
+under one heading. The server puts all three in the `blog` group; a section whose screen is not
+here yet is silently left out of the menu.
+
+`blog({ path: '/writing' })` puts the sections somewhere else inside the panel.
+
+## The list
+
+A page of articles, newest first, with whatever is pinned above them. Over it: the views of the
+same list as tabs — everything, live, scheduled, drafts, taken off the site, and the bin — a
+search box, and three dropdowns for the rubric, the tag and the author. All of it lives in the
+address, so opening an article and coming back lands on the same page of the same filter.
+
+Five states, and the pair worth knowing apart is the last two: an article that was never
+published and one that was taken off the site this morning both have no publication date, and
+only its history tells them apart. Calling the second one a draft would be a lie.
+
+Below 640 pixels the row becomes a card: the cover on the left, the title, one rubric, the
+state, the date and the author beside it. Ten articles on a phone screen instead of two.
+
+## Licence
+
+MIT

package/dist/ArticleAddress.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/ArticleAuthor.d.ts

@@ -0,0 +1,14 @@
+type __VLS_Props = {
+    disabled?: boolean;
+};
+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;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/ArticleCreateDialog.d.ts

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

package/dist/ArticleEditorPage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The editor of one article: a head that stays put, and the described screen under it.
+ *
+ * What this page owns is the head — what the article is called, what state it is in, and the
+ * way out to the site — and the bar along the bottom, which is where it is saved and published.
+ * Everything between them is `blog.article-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.
+ *
+ * The one thing here that a page editor does not have is the day. An article carries a date
+ * that may be in the future, so "publish" means "publish under the date in the settings tab",
+ * and the bar says which day that is before it is pressed (§7).
+ */
+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/ArticleHistory.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/ArticleRelated.d.ts

@@ -0,0 +1,14 @@
+type __VLS_Props = {
+    disabled?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: number[];
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: number[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: number[]) => any) | undefined;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/ArticleRubrics.d.ts

@@ -0,0 +1,14 @@
+type __VLS_Props = {
+    disabled?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: number[];
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: number[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: number[]) => any) | undefined;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/ArticleTags.d.ts

@@ -0,0 +1,14 @@
+type __VLS_Props = {
+    disabled?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: number[];
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: number[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: number[]) => any) | undefined;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/ArticlesPage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The section: a page of articles with the filters of §10 over it.
+ *
+ * A paginator rather than a tree, which is the whole difference from `Pages`: articles all sit
+ * at the same depth and there are a hundred of them, so the screen is twenty rows, a filter bar
+ * and a page number.
+ *
+ * Below {@link CARDS} the row becomes a card, and the card is not the table's own stack of
+ * labelled lines: at 375px five of those are four hundred pixels for one article. It is the
+ * cover on the left and everything else beside it, which is 96px and ten articles on a screen
+ * instead of two (§10). The table draws whatever columns it is given, so the switch is made
+ * here — one column at that width, seven above it — and both halves agree on the number because
+ * it is the same constant.
+ */
+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/RubricForm.d.ts

@@ -0,0 +1,39 @@
+import { RubricRow } from './types';
+/**
+ * One rubric, in the pane beside the list (§10).
+ *
+ * Six fields and nothing described: nothing patches a rubric, so there is no screen to extend
+ * and no registry to go through. What it does borrow from the described screens are the two
+ * fields it has no business drawing itself — the library picker and the SEO card, both looked
+ * up in the panel's own type registry. A panel without `module-media` still edits everything
+ * else; it simply has no picture.
+ *
+ * The SEO card starts folded, with a sentence about where the page's title comes from without
+ * it. That is the truth for most rubrics — the rules cover them — and a card of ten empty
+ * fields under every form teaches editors to fill in ten empty fields (§12).
+ */
+type __VLS_Props = {
+    /** `null` while a new one is being made: the form of a row that is not in the list yet. */
+    rubric: RubricRow | null;
+    /** The first segment of every blog address, for the line under the slug (§4). */
+    prefix?: string;
+    /** False when the pane is a drawer over the list, which is where the way back lives. */
+    inline?: boolean;
+    disabled?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    articles: (rubric: RubricRow) => any;
+    deleted: () => any;
+    back: () => any;
+    saved: (rubric: RubricRow) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onArticles?: ((rubric: RubricRow) => any) | undefined;
+    onDeleted?: (() => any) | undefined;
+    onBack?: (() => any) | undefined;
+    onSaved?: ((rubric: RubricRow) => any) | undefined;
+}>, {
+    disabled: boolean;
+    prefix: string;
+    inline: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/RubricsPage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The sections of the blog: the menu on the left, the one that is open on the right (§10).
+ *
+ * `WxListDetail` rather than a list and a form on two screens, and the reason is the drag. The
+ * order of this list *is* the order of the menu on the site (§6), so it is edited by moving
+ * rows — and a screen where moving a row means leaving the record you were editing is a screen
+ * where nobody reorders anything.
+ *
+ * There is no paginator and no search: a rubric is a section, a site has eight of them, and a
+ * menu you have to search is a menu that is already wrong.
+ */
+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, {}, HTMLDivElement>;
+export default _default;

package/dist/TagCreateDialog.d.ts

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

package/dist/TagMergeDialog.d.ts

@@ -0,0 +1,20 @@
+import { TagRow } from './types';
+/**
+ * Several tags into one (§6).
+ *
+ * The dialog asks the one question the selection cannot answer — which of them stays — and says
+ * the two things about the operation that an editor has to know before pressing it: how many
+ * articles change hands, and that nothing here can be undone. The pivot rows that go are gone,
+ * and putting a tag back would not put back which articles carried it.
+ *
+ * The checkbox is the other half. The aliases of `webx-ui/routing` die with the tag — they are
+ * rows keyed to the entity — so an address that is to survive the merge has to survive as
+ * something that is not tied to it, which is a redirect. That is a permanent fact about the
+ * site, and a tag made by mistake this morning does not deserve one, so it is asked rather than
+ * done quietly.
+ */
+type __VLS_Props = {
+    tags: TagRow[];
+};
+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/TagsPage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tags, and the raking over of them (§10).
+ *
+ * Entered from the article form by the hundred, which is what the whole screen is shaped by:
+ * within six months the table holds "belts", "belt" and "drive belts", and all three are right.
+ * So renaming is done in place — a tag is one word, and a form to change one word is a form
+ * nobody opens — and everything else is done to a pile of rows at once.
+ *
+ * It stays a table at every width, with columns dropping out by `hideBelow` until the word and
+ * the `···` are left. Cards would be 250px each for a word and a number (CLAUDE.md §4), and
+ * this is a screen somebody scrolls through sixty rows of.
+ *
+ * "Not indexed" is the one filter that is not a `where`: it is the answer of the same rule the
+ * rendered page follows, rules in the SEO section included, so the column, the tab's count and
+ * the filter are one answer worked out on the server (§12).
+ */
+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, {
+    box: HTMLSpanElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,56 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { ArticleDetail, ArticleInput, ArticleQuery, ArticleRow, ArticleSave, ArticleVersion, ArticlesPage, BlogTag, RubricInput, RubricRow, RubricsPayload, TagInput, TagMassAction, TagMerged, TagQuery, TagRow, TagsPage } from './types';
+export interface BlogApi {
+    /** A page of articles, with what the filters over them can be set to. */
+    articles(query?: ArticleQuery): Promise<ArticlesPage>;
+    /** One article as its editor opens it: the record, the screen's values and the revision. */
+    get(id: number): Promise<ArticleDetail>;
+    create(input: ArticleInput): Promise<ArticleRow>;
+    /**
+     * Save. Refused with a 409 when the revision is not the current one — the body is an
+     * {@link ArticleConflict} carrying the article as it now is, so the panel can offer to
+     * re-read rather than quietly keep one of two edits.
+     */
+    save(id: number, input: ArticleSave): Promise<ArticleDetail>;
+    /** Throw away what is waiting and keep what the site is showing. */
+    discard(id: number): Promise<ArticleDetail>;
+    /** The publications, newest first. */
+    versions(id: number): Promise<ArticleVersion[]>;
+    /** An old publication becomes the draft; putting it on the site is a separate step. */
+    restoreVersion(id: number, number: number): Promise<ArticleDetail>;
+    /** Tags matching what is being typed, most used first. */
+    tags(term?: string): Promise<BlogTag[]>;
+    /**
+     * A tag made from the article being written, because that is where tags come from (§2.8) —
+     * and from the tags screen, which is the other place somebody spells a new word.
+     */
+    createTag(input: TagInput): Promise<TagRow>;
+    /** On the site. `at` in the future schedules it; left out, it goes on now (§7). */
+    publish(id: number, at?: string | null): Promise<ArticleRow>;
+    unpublish(id: number): Promise<ArticleRow>;
+    remove(id: number): Promise<void>;
+    restore(id: number): Promise<ArticleRow>;
+    /** Every rubric there is, in the order the menu of the site has them (§6). */
+    rubrics(): Promise<RubricsPayload>;
+    createRubric(input: RubricInput): Promise<RubricRow>;
+    saveRubric(id: number, input: RubricInput): Promise<RubricRow>;
+    /**
+     * Into the bin — refused with a 422 naming the number of articles while it still holds any
+     * (§6). The panel keeps the button out of reach, so reaching this is somebody else's save
+     * landing between the list and the click.
+     */
+    removeRubric(id: number): Promise<void>;
+    /** The whole order, as it is on screen. */
+    sortRubrics(ids: number[]): Promise<void>;
+    /** A page of tags with the counts the pills wear (§10). */
+    tagsPage(query?: TagQuery): Promise<TagsPage>;
+    /** A rename, or the switch on the index. Only what travels is touched. */
+    saveTag(id: number, input: TagInput): Promise<TagRow>;
+    removeTag(id: number): Promise<void>;
+    /** What the selection bar does to a pile of them at once. */
+    massTags(ids: number[], action: TagMassAction): Promise<number>;
+    /** Several into one. Irreversible, and `redirect` is what outlives the tags that go (§6). */
+    mergeTags(ids: number[], keep: number, redirect: boolean): Promise<TagMerged>;
+}
+/** Everything under `/blog`, below the panel's API path. */
+export declare function createBlogApi(admin: AdminContext): BlogApi;

package/dist/editor.d.ts

@@ -0,0 +1,56 @@
+import { InjectionKey, Ref } from 'vue';
+import { ScreenModel } from '@webx-ui/schema';
+import { ArticleDetail, ArticleOption, ArticleRow } from './types';
+/**
+ * What the editor knows and the nodes of its screen do not.
+ *
+ * The form is a described screen (`blog.article-form`), so the parts of it that need more than
+ * a value — the address printed whole, the rubrics with their titles, the history — arrive as
+ * node types of their own. Each of those needs the article being edited and the lists the
+ * server sent with it, and none of them can be handed either 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 ArticleEditorContext {
+    /** The article as the server last answered it, or `null` while the first request is in flight. */
+    article: Ref<ArticleRow | null>;
+    /**
+     * 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>;
+    /** What the dropdowns on the screen can be set to, as the record carried them. */
+    options: Ref<ArticleDetail['options']>;
+    /** Titles for the ids in `values.related` — the only place they come from. */
+    related: Ref<ArticleOption[]>;
+    /** The first segment of every blog address, for the field that edits the last one. */
+    prefix: Ref<string>;
+    /** Where the section lives, for the links the nodes draw. */
+    base: string;
+    /** Whether this administrator may write at all. */
+    canManage: boolean;
+    /**
+     * Whether the screen is closed for writing right now — no permission, or a publication in
+     * flight.
+     *
+     * Through the editor rather than through the form, because `WxForm`'s own `disabled` reaches
+     * a control only through `useFormField`, which the design system does not hand out: a field
+     * built outside `@webx-ui/core` has no way to ask. The screen is told the same thing twice —
+     * once for the fields that are core's and once here — and both are computed from one place.
+     */
+    disabled: Ref<boolean>;
+    /** Ask the server for the article again — after a restore, a publication, a discard. */
+    reload(): Promise<void>;
+    /** Write the draft now rather than at the end of the next pause. */
+    save(): Promise<void>;
+}
+export declare const articleEditorKey: InjectionKey<ArticleEditorContext>;
+export declare function provideArticleEditor(editor: ArticleEditorContext): void;
+/**
+ * The editor above this node, or `null` outside one — a node of `blog.article-form` drawn in a
+ * demo or a test has no article to talk about, and must draw nothing rather than throw.
+ */
+export declare function useArticleEditor(): ArticleEditorContext | 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 useBlogMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { blog, type BlogOptions } from './module';
+export { createBlogApi, type BlogApi } from './api';
+export { blogMessages } from './messages';
+export { articleEditorKey, provideArticleEditor, useArticleEditor, type ArticleEditorContext, } from './editor';
+export { default as WxArticlesPage } from './ArticlesPage';
+export { default as WxRubricsPage } from './RubricsPage';
+export { default as WxRubricForm } from './RubricForm';
+export { default as WxTagsPage } from './TagsPage';
+export { default as WxTagCreateDialog } from './TagCreateDialog';
+export { default as WxTagMergeDialog } from './TagMergeDialog';
+export { default as WxArticleCreateDialog } from './ArticleCreateDialog';
+export { default as WxArticleEditorPage } from './ArticleEditorPage';
+export { default as WxArticleAddress } from './ArticleAddress';
+export { default as WxArticleAuthorField } from './ArticleAuthor';
+export { default as WxArticleRubrics } from './ArticleRubrics';
+export { default as WxArticleTags } from './ArticleTags';
+export { default as WxArticleRelated } from './ArticleRelated';
+export { default as WxArticleHistory } from './ArticleHistory';
+export type { ArticleAuthor, ArticleConflict, ArticleCover, ArticleDetail, ArticleFilters, ArticleInput, ArticleOption, ArticleQuery, ArticleRow, ArticleSave, ArticleStatus, ArticleVersion, ArticlesPage, BlogNamed, BlogTag, RubricInput, RubricRow, RubricsPayload, TagCounts, TagIndexing, TagInput, TagMassAction, TagMerged, TagQuery, TagRow, TagsPage, } from './types';