@webx-ui/module-catalog 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,57 @@
+# @webx-ui/module-catalog
+
+The front end of the catalogue of the [WebX UI](https://github.com/webx-ui/webx-ui) admin panel:
+products with their gallery, a tree of categories with the filters each shows, and «Deleted».
+
+The other half is the Composer package `webx-ui/module-catalog`, which owns the products, the
+categories, their addresses, the search engine and the API. The section appears in the panel when
+both halves are installed.
+
+## Install
+
+```bash
+npm install @webx-ui/module-catalog
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { catalog } from '@webx-ui/module-catalog'
+import '@webx-ui/module-catalog/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [catalog()],
+}).mount()
+```
+
+`catalog()` is one section — the server registers one module, `catalog` — which opens on the
+products; the tree of categories and «Deleted» are reached from its head. The satellites
+(`module-catalog-*`) stand beside it in the `catalog` group of the navigation.
+
+Keep the default path (`/catalog`): the server's refusal of a taken article number links to
+`{panel}/catalog/products/{id}`.
+
+## Screens
+
+| Route                      | Screen                                                                     |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `/catalog/products`        | the list: search, views, facets from `/facets`, satellites' columns, picks |
+| `/catalog/products/{id}`   | `catalog.product-form` — a described screen, patched by satellites         |
+| `/catalog/categories`      | the tree with the number of products in each branch, dragged into place    |
+| `/catalog/categories/{id}` | `catalog.category-form`, with the «Filters» tab                            |
+| `/catalog/deleted`         | «Deleted», products and categories, each with «Restore»                    |
+
+The list keeps what it is looking at in the address — `view`, `q`, `sort`, `page`, and a
+parameter per facet: `f.category=2,5`, `f.price=100-500`, `f.in-stock=1`.
+
+## Screen node types
+
+| Type                  | What it is                                                                    |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `wx-catalog-category` | a category from the tree; `props.multiple` for several                        |
+| `wx-catalog-facets`   | a category's own facet setting, or where it inherits one from                 |
+| `wx-catalog-gallery`  | the product's pictures: added, ordered and captioned by requests of their own |
+
+## License
+
+MIT

package/dist/BulkBar.d.ts

@@ -0,0 +1,20 @@
+import { BulkSelection } from './types';
+/**
+ * The actions over what is picked in the list (§11.4), and the run they start.
+ *
+ * Which actions there are is the server's answer — the core's and every satellite's, only the
+ * ones this administrator may start. A small selection is done inside the request and answered at
+ * once; a large one is a run in the background, polled here with its progress, and its refusals
+ * are listed by product when it ends. The list reloads either way, and `finished` carries the ids
+ * that refused — what the list leaves picked, so they can be put right and tried again.
+ */
+type __VLS_Props = {
+    count: number;
+    selection: BulkSelection;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    finished: (refused: number[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onFinished?: ((refused: number[]) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/BulkParamsDialog.d.ts

@@ -0,0 +1,12 @@
+import { BulkActionInfo } from './types';
+/**
+ * What a bulk action asks for before it runs — a category, a label — and the last word before it
+ * does: how many products it is about to touch. The fields are drawn from what the server said
+ * about the action, so a satellite's action gets its dialog without this file knowing it.
+ */
+type __VLS_Props = {
+    action: BulkActionInfo;
+    count: number;
+};
+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/CategoriesPage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The shelves of the catalogue: the whole tree at once, with how many products each holds
+ * (§6.1), dragged into place.
+ *
+ * Whole, not a level at a time as the pages are: a catalogue has dozens of categories, not
+ * thousands, and the counts are one query for all of them on the server. A drag moves a category
+ * and everything under it; the addresses do not move with it — they are flat (decision 23) — so
+ * no drop is ever questioned, unlike a page's.
+ *
+ * Publication is here as well as on the form, because taking a branch off the site is a thing
+ * done to the tree: an unpublished category hides everything below it (§6.3), and the rows under
+ * it say so.
+ *
+ * A search puts the tree away and lists the matches flat — a branch drawn for one match deep
+ * inside it tells the reader nothing they asked about.
+ */
+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/CategoryCreateDialog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A new category: its name and where it hangs. Created unpublished — a shelf nobody filled is
+ * not one to show visitors — at the end of its parent's children; the tree is where it is dragged
+ * into place. The address is made of the name, and a taken one is refused under the name.
+ */
+type __VLS_Props = {
+    parent?: number | null;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    parent: number | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    field: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/CategoryEditorPage.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/CategoryField.d.ts

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

package/dist/DeletedPage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * «Deleted» (§5, §6.3): what was deleted, and the one thing that can be done to it — bring it
+ * back. There is no "delete for ever": orders will point at products, and their links have to
+ * keep answering. No filters either; a search finds what somebody is looking for, and the list
+ * is newest first, which is where a regret usually is.
+ *
+ * Products and categories are two tabs of one screen rather than two screens, because the
+ * question a reader comes with is "where did it go", not which kind of thing it was.
+ *
+ * A row says what a restore will do to it before it is done: a product whose category is
+ * deleted too comes back without one and unpublished, and that is worth knowing first.
+ */
+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/FacetsField.d.ts

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

package/dist/GalleryField.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/ProductCreateDialog.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/ProductEditorPage.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/ProductsPage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The products of the catalogue (§11.1): a page of rows, the views of decision 3 over it, the
+ * facets as filters behind the funnel, and a checkbox per row.
+ *
+ * The checkboxes are for the bulk actions (§11.4): a selection outlives the page it was made on,
+ * which is what "select these twelve across three pages" needs, and "everything found" picks the
+ * filter itself rather than its ids. The actions and their progress are `BulkBar`'s.
+ *
+ * What the list shows beyond the core's columns is the satellites' (`ProductColumns`, §7.4): the
+ * server says which, and each row carries its values under their keys.
+ */
+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,59 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { Paginated } from '@webx-ui/core';
+import { ScreenModel } from '@webx-ui/schema';
+import { BulkActionInfo, BulkRun, BulkSelection, CategoryDetail, CategoryNode, CategoryRow, DeletedCategory, DeletedKind, DeletedProduct, FacetRegistryAnswer, ProductDetail, ProductImage, ProductQuery, ProductRow, ProductsPage } from './types';
+export interface CatalogApi {
+    products(query?: ProductQuery): Promise<ProductsPage>;
+    product(id: number): Promise<ProductDetail>;
+    /** The values of `catalog.product-form`; a refused field comes back as a 422 under its name. */
+    createProduct(values: ScreenModel): Promise<ProductDetail>;
+    saveProduct(id: number, values: ScreenModel): Promise<ProductDetail>;
+    removeProduct(id: number): Promise<void>;
+    restoreProduct(id: number): Promise<ProductRow>;
+    /** A file off the disk, with how far it has got; or an address the server fetches itself. */
+    addImage(id: number, source: File | string, onProgress?: (percent: number) => void): Promise<ProductImage>;
+    /** The whole gallery in its order, with every picture's words (§11.2). */
+    saveImages(id: number, images: Pick<ProductImage, 'id' | 'alt' | 'title'>[]): Promise<ProductImage[]>;
+    removeImage(id: number, image: number): Promise<void>;
+    categories(): Promise<CategoryNode[]>;
+    category(id: number): Promise<CategoryDetail>;
+    createCategory(values: ScreenModel, parent: number | null): Promise<CategoryDetail>;
+    saveCategory(id: number, values: ScreenModel): Promise<CategoryDetail>;
+    /** Under `parent` (null — the top), before `before` (null — last). Answers with the whole tree. */
+    moveCategory(id: number, parent: number | null, before: number | null): Promise<CategoryNode[]>;
+    removeCategory(id: number): Promise<void>;
+    restoreCategory(id: number): Promise<CategoryRow>;
+    /** The registry of facets, with the sorts the list is offered. */
+    facets(): Promise<FacetRegistryAnswer>;
+    /** The bulk actions this administrator may start, with what each asks for (§11.4). */
+    bulkActions(): Promise<BulkActionInfo[]>;
+    /** Done at once when small (`id` null in the answer), queued otherwise. */
+    startBulk(action: string, params: Record<string, unknown>, selection: BulkSelection): Promise<BulkRun>;
+    bulkRun(id: number): Promise<BulkRun>;
+    deleted(kind: 'products', query?: {
+        q?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<Paginated<DeletedProduct>>;
+    deleted(kind: 'categories', query?: {
+        q?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<Paginated<DeletedCategory>>;
+    deleted(kind: DeletedKind, query?: {
+        q?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<Paginated<DeletedProduct | DeletedCategory>>;
+}
+/** The path of the catalogue under the panel's API. */
+export declare const CATALOG_API = "catalog";
+/**
+ * The list's query as Laravel reads nested parameters: `facets[brand][]=3`,
+ * `facets[price][min]=100`. Every facet's choice is a list, a toggle's too — on is
+ * `facets[in-stock][]=1`, the value the storefront's own links send; a bare `facets[in-stock]=1`
+ * is refused. Empty choices are left out, so a filter that was opened and closed again asks for
+ * nothing.
+ */
+export declare function productSearch(query: ProductQuery): URLSearchParams;
+export declare function createCatalogApi(admin: AdminContext): CatalogApi;

package/dist/editor.d.ts

@@ -0,0 +1,41 @@
+import { InjectionKey, Ref } from 'vue';
+import { CategoryRow, ProductImage, ProductRow } from './types';
+/**
+ * What the product editor knows and the nodes of `catalog.product-form` do not.
+ *
+ * The gallery needs it most: its pictures are not a value of the form but records of their own,
+ * added, ordered and captioned by requests of their own (§11.2), so the node has to know which
+ * product it is attached to and whether this administrator may write.
+ */
+export interface ProductEditorContext {
+    /** The product as the server last answered it, or `null` while the first request is out. */
+    product: Ref<ProductRow | null>;
+    /** The gallery in its order. The editor reads it with the product; the node keeps it. */
+    images: Ref<ProductImage[]>;
+    /** Closed for writing: no permission, or a save in flight. */
+    locked: Ref<boolean>;
+}
+export declare const productEditorKey: InjectionKey<ProductEditorContext>;
+export declare function provideProductEditor(editor: ProductEditorContext): void;
+/** The editor above this node, or `null` outside one — a demo or a test draws a placeholder. */
+export declare function useProductEditor(): ProductEditorContext | null;
+/**
+ * What the category editor knows and `wx-catalog-facets` needs: which category it is, so that the
+ * field can say whose setting it inherits — the parent's, the grandparent's, or nobody's (§6.2).
+ */
+export interface CategoryEditorContext {
+    category: Ref<CategoryRow | null>;
+    /** Closed for writing — what the screen's form says to its own controls, for the ones it cannot. */
+    locked: Ref<boolean>;
+    /**
+     * The server's answer to "whose facet setting does it show" (`facets_from`): the ancestor, `null`
+     * for its own or the default, `undefined` when the server did not say.
+     */
+    facetsFrom: Ref<{
+        id: number;
+        name: string;
+    } | null | undefined>;
+}
+export declare const categoryEditorKey: InjectionKey<CategoryEditorContext>;
+export declare function provideCatalogCategoryEditor(editor: CategoryEditorContext): void;
+export declare function useCatalogCategoryEditor(): CategoryEditorContext | null;

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The first refusal of a field, whether the server named the field (`name`) or one language of it
+ * (`name.en`). Matched on the name and a dot, not on the first dot of the key: names with a dot in
+ * them exist (`stock.status`), and `name.en` must not be read as the field `name.en`.
+ */
+export declare function firstError(errors: Record<string, string[]>, field: string): string | undefined;

package/dist/filters.d.ts

@@ -0,0 +1,18 @@
+import { LocationQuery } from 'vue-router';
+import { FacetChoice, FacetInfo } from './types';
+/**
+ * The list's facet filters live in the address, one parameter per facet — `f.<key>` — so that
+ * coming back from a product lands on the same filter, and a filtered list can be linked to
+ * (the tree's "Show its products" does exactly that):
+ *
+ *     f.category=12,14   values of a terms or tree facet
+ *     f.price=100-500    a range; either end may be empty
+ *     f.in-stock=1       a toggle
+ *
+ * The server's own format is another (`facets[key][]=…`, see `productSearch()`); this one is for
+ * a person reading the address bar.
+ */
+export declare const FACET_PREFIX = "f.";
+export declare function readFacets(query: LocationQuery, facets: FacetInfo[]): Record<string, FacetChoice>;
+/** One facet's choice as its parameter; `undefined` takes the parameter away. */
+export declare function writeFacet(choice: FacetChoice | null | undefined): string | undefined;

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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { catalog, type CatalogOptions } from './module';
+export { createCatalogApi, productSearch, CATALOG_API, type CatalogApi } from './api';
+export { catalogMessages } from './messages';
+export { provideProductEditor, productEditorKey, useProductEditor, provideCatalogCategoryEditor, categoryEditorKey, useCatalogCategoryEditor, type ProductEditorContext, type CategoryEditorContext, } from './editor';
+export { useCategoryTree, useFacetRegistry, type CategoryTree, type FacetRegistry } from './store';
+export { default as WxCatalogProductsPage } from './ProductsPage';
+export { default as WxCatalogProductEditor } from './ProductEditorPage';
+export { default as WxCatalogProductCreateDialog } from './ProductCreateDialog';
+export { default as WxCatalogCategoriesPage } from './CategoriesPage';
+export { default as WxCatalogCategoryEditor } from './CategoryEditorPage';
+export { default as WxCatalogCategoryCreateDialog } from './CategoryCreateDialog';
+export { default as WxCatalogDeletedPage } from './DeletedPage';
+export { default as WxCatalogCategoryField } from './CategoryField';
+export { default as WxCatalogFacetsField } from './FacetsField';
+export { default as WxCatalogGallery } from './GalleryField';
+export type { CategoryDetail, CategoryNode, CategoryRef, CategoryRow, DeletedCategory, DeletedKind, DeletedProduct, FacetChoice, FacetInfo, FacetKind, FacetSetting, ProductColumnInfo, ProductDetail, ProductImage, ProductQuery, ProductRow, ProductSort, ProductState, ProductsPage, SkuHolder, } from './types';