@webx-ui/module-banners 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-banners
+
+The front end of the banners section of the [WebX UI](https://github.com/webx-ui/webx-ui) admin
+panel: pictures (and a narrower one for a phone), an optional video, a title, a text and up to
+three buttons, standing in **named places** and arranged by hand.
+
+The other half is the Composer package `webx-ui/module-banners`, which owns the places, the banners,
+`banners()` and `banners_layout()` for templates and the API. A section appears in the panel when
+both halves are installed. Banners reach a site only through a template helper: the site's own
+markup draws them.
+
+## Install
+
+```bash
+npm install @webx-ui/module-banners
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { banners } from '@webx-ui/module-banners'
+import '@webx-ui/module-banners/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [banners()],
+}).mount()
+```
+
+`banners()` is one section and one entry of the menu, at the top level. `banners({ path: '/promo' })`
+puts it somewhere else inside the panel.
+
+## Places and banners
+
+`/banners` is the places on the left and the banners of one of them on the right. A place the
+site's config declares is on the list before anything was saved into it, carries a lock and cannot
+be renamed or deleted here: a template asks for it by key, and the list says how —
+`banners('hero')`. A place of somebody's own is made with **New place**, renamed from its row, and
+deleted only when it is empty, the bin included.
+
+The banners of a place are in the order the site shows them: drag the grip, or pick it up with the
+keyboard (space, arrows, space). A switched-off banner stays in its place, quieter; the bin is the
+same list turned over, and a banner comes back from it with **Restore**.
+
+A banner opens on a page of its own (`/banners/<id>`, a new one at `/banners/new?place=<key>`):
+the place above the described screen `banners.form`, one **Save** under it, Ctrl+S, and a question
+before leaving with something unsaved. Moved to another place, a banner stands last in it. A new
+banner starts switched off.
+
+The guide — places, the two helpers, a complete template with its styles and slider script, the
+agent's tools — is at https://webx-ui.github.io/webx-ui/guide/banners.

package/dist/BannerEditorPage.d.ts

@@ -0,0 +1,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, {}, HTMLDivElement>;
+export default _default;

package/dist/BannersPage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The section: the places of the site on the left, the banners of one of them on the right
+ * (§5.4) — the shape of the menus, for the same reason: somebody who opens this is arranging one
+ * place, not choosing between them, so the first one opens by itself where there is room for it.
+ * On a phone it does not: there the same line would raise a panel over a list nobody touched.
+ *
+ * A declared place is on the list before anything was ever saved into it (decision 1) — its row
+ * in the table is made by its first banner — so places are named by key throughout, not by id.
+ */
+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/PlaceDialog.d.ts

@@ -0,0 +1,10 @@
+import { PlaceRow } from './types';
+type __VLS_Props = {
+    place?: PlaceRow | null;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    place: PlaceRow | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    field: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/PlacePane.d.ts

@@ -0,0 +1,17 @@
+import { PlaceRow } from './types';
+type __VLS_Props = {
+    place: PlaceRow;
+    base: string;
+    /** False in the drawer a narrow screen opens this in. */
+    inline?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    back: () => any;
+    changed: () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onBack?: (() => any) | undefined;
+    onChanged?: (() => any) | undefined;
+}>, {
+    inline: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,31 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { ScreenModel } from '@webx-ui/schema';
+import { BannerDetail, BannerRow, PlaceInput, PlaceRow } from './types';
+export interface BannersApi {
+    /** Every place: the declared ones in the config's order, then the own ones by name. */
+    places(): Promise<PlaceRow[]>;
+    createPlace(input: PlaceInput): Promise<PlaceRow>;
+    /** Only a place of somebody's own, and only its name: the key is what a template asks for. */
+    renamePlace(key: string, title: PlaceInput['title']): Promise<PlaceRow>;
+    /** Only an own place with nothing in it, the bin included — a 422 with the count otherwise. */
+    removePlace(key: string): Promise<void>;
+    /** The banners of a place in their order, or its bin. A declared place without a row: `[]`. */
+    list(place: string, trashed?: boolean): Promise<BannerRow[]>;
+    get(id: number): Promise<BannerDetail>;
+    /**
+     * A new banner out of the values of its form, in one request: the form is filled in first and
+     * the record made on the first save, so nobody leaves an empty banner in a place.
+     */
+    create(place: string, values: ScreenModel): Promise<BannerDetail>;
+    /**
+     * Refused with a 422 under the name of the field — `buttons.<n>.link` for a button's row. A
+     * `place` other than the one it stands in moves it to the end of that one (decision 14).
+     */
+    save(id: number, values: ScreenModel, place?: string): Promise<BannerDetail>;
+    remove(id: number): Promise<void>;
+    restore(id: number): Promise<BannerRow>;
+    /** The order of one place, written whole. */
+    reorder(place: string, ids: number[]): Promise<void>;
+}
+/** Everything under `/banners`, below the panel's API path (§5.6). */
+export declare function createBannersApi(admin: AdminContext): BannersApi;

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 useBannersMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { banners, type BannersOptions } from './module';
+export { createBannersApi, type BannersApi } from './api';
+export { bannersMessages } from './messages';
+export { default as WxBannersPage } from './BannersPage';
+export { default as WxBannerEditorPage } from './BannerEditorPage';
+export type { BannerButton, BannerDetail, BannerRow, BannerSummary, PlaceInput, PlaceRow, } from './types';