@aglyn/plugins-commerce 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/components/console/product-zones.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The zones this plugin hosts on its product surfaces (AGL-2916): the product
+ * editor, the products hub and the CSV import dialog.
+ *
+ * Each is drawn through the shell's renderer (`useConsoleWidgetSlot`), so a
+ * widget there passes the same enablement, entitlement and permission gates as
+ * one on a console page. The props are this plugin's words for its catalog,
+ * declared on the zone's token; a widget from another plugin restates the
+ * shape it reads rather than importing this package. A widget proposes and
+ * never writes: every write is this plugin's, with the guards it carries.
+ */
+/** A product type, as the commerce catalog names it. */
+export type ConsoleProductType = 'physical' | 'digital' | 'service';
+/** A product option axis: its name and the values a shopper picks from. */
+export interface ConsoleProductOption {
+    name: string;
+    values: string[];
+}
+/** A product as the commerce editor holds it: saved, or staged and unsaved. */
+export interface ConsoleProductDraft {
+    /** `null` for a product nobody has saved yet. */
+    id: string | null;
+    name: string;
+    type: ConsoleProductType;
+    description: string;
+    tags: string[];
+    categoryIds: string[];
+    options: ConsoleProductOption[];
+    /** The product's media, in order; the first is the photo the storefront leads with. */
+    mediaUrls: string[];
+    seoTitle: string;
+    seoDescription: string;
+}
+/**
+ * Copy a widget proposes for one product. A field left out is left alone;
+ * `optionNames` renames the product's options in order, keeping every
+ * variant, and is ignored unless it names each option once.
+ */
+export interface ConsoleProductCopyValues {
+    description?: string;
+    tags?: string[];
+    categoryIds?: string[];
+    optionNames?: string[];
+    seoTitle?: string;
+    seoDescription?: string;
+}
+/**
+ * What the `productEditor` zone hands each widget: the product as the editor
+ * holds it, and `proposeValues`, which stages copy in the editor as unsaved
+ * edits. The zone sits under the product's description, tags and categories,
+ * as the editor's search listing hosts `seoFields`. Save product is the
+ * write, with the guards it carries.
+ */
+export interface ConsoleProductEditorZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` where the host does not know it. */
+    orgId: string | undefined;
+    product: ConsoleProductDraft;
+    /** The site's categories, as the editor's picker lists them. */
+    categories: ReadonlyArray<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Stages `values` in the editor as unsaved edits under `key`. Save product
+     * is what stores them; a widget never writes the product itself.
+     */
+    proposeValues: (values: ConsoleProductCopyValues, key: string) => void;
+}
+/** A catalog row as the products hub holds it. */
+export interface ConsoleProductSummary {
+    id: string;
+    name: string;
+    status: 'draft' | 'active' | 'archived';
+    /** Whether a variant of the product has no price yet. */
+    priceMissing: boolean;
+    /** Whether the product has a photo. */
+    hasPhoto: boolean;
+}
+/** A new product a widget asks the hub to create, always as a draft with no price. */
+export interface ConsoleProposedProduct {
+    name: string;
+    type: ConsoleProductType;
+    description: string;
+    tags: string[];
+    options: ConsoleProductOption[];
+    seoTitle: string;
+    seoDescription: string;
+}
+/** A discount a widget asks the hub to create, always switched off. */
+export interface ConsoleProposedDiscount {
+    name: string;
+    /** The code a shopper types, or `null` for a discount that applies on its own. */
+    code: string | null;
+    kind: 'percent' | 'fixed' | 'free_shipping';
+    valuePct: number | null;
+    valueCents: number | null;
+    minSubtotalCents: number | null;
+}
+/**
+ * What the `productsHub` zone hands each widget: the catalog rows the hub
+ * holds, the products its latest import created, and the hub's own writes a
+ * widget may ask it to make — copy onto saved products, new draft products,
+ * categories and switched-off discounts. The zone sits above the catalog
+ * table. Each write is the hub's, with its seed, allowance and slug checks; a
+ * widget writes nothing itself. Every write resolves once it is stored and
+ * throws with a message a person can act on when the hub refuses it: an
+ * allowance the plan has no room for, a product that is gone.
+ *
+ * The creates are safe to ask twice: a product or a category named like one
+ * the site has, and a discount with the code (or, with no code, the name) of
+ * one the site has, are passed over, so a proposal applied again, by anyone,
+ * creates nothing it already created.
+ */
+export interface ConsoleProductsHubZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` where the host does not know it. */
+    orgId: string | undefined;
+    /** The catalog rows the hub holds, in its order. */
+    products: readonly ConsoleProductSummary[];
+    /**
+     * The products the hub's latest CSV import created in this visit, and the
+     * options the `productImport` zone set for them; `null` before any import.
+     * `key` is new for each import.
+     */
+    lastImport: {
+        key: string;
+        productIds: readonly string[];
+        options: Readonly<Record<string, boolean>>;
+    } | null;
+    /** Writes copy onto a saved product, read fresh from the store. */
+    applyProductCopy: (productId: string, values: ConsoleProductCopyValues) => Promise<void>;
+    /** Creates each product as a draft with no price, and resolves with the ids it created. */
+    createProductDrafts: (products: readonly ConsoleProposedProduct[]) => Promise<string[]>;
+    /** Creates categories by name, and resolves with how many it created. */
+    createCategories: (names: readonly string[]) => Promise<number>;
+    /** Creates each discount switched off, and resolves with how many it created. */
+    createDiscountDrafts: (discounts: readonly ConsoleProposedDiscount[]) => Promise<number>;
+}
+/**
+ * What the `productImport` zone hands each widget, inside the CSV import
+ * dialog: how many products the import creates, and options a widget sets
+ * for what happens to them once they land. The hub hands the options, with
+ * the ids of the products the import created, to `productsHub` as its
+ * `lastImport`.
+ */
+export interface ConsoleProductImportZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` where the host does not know it. */
+    orgId: string | undefined;
+    /** How many products the import creates. */
+    count: number;
+    /** The options set for this import, by key. */
+    options: Readonly<Record<string, boolean>>;
+    /** Sets one option; the hub carries it to `productsHub` with what the import created. */
+    setOption: (key: string, on: boolean) => void;
+}
+export declare const PRODUCT_EDITOR_ZONE: import("@aglyn/aglyn/plugin-manager/plugin-zones").PluginZone<ConsoleProductEditorZoneProps>;
+export declare const PRODUCTS_HUB_ZONE: import("@aglyn/aglyn/plugin-manager/plugin-zones").PluginZone<ConsoleProductsHubZoneProps>;
+export declare const PRODUCT_IMPORT_ZONE: import("@aglyn/aglyn/plugin-manager/plugin-zones").PluginZone<ConsoleProductImportZoneProps>;
+/**
+ * Declares the three zones, from the console registrar. The ids are the ones
+ * widgets have always registered under, so a widget written for them keeps
+ * working. Each is `bare`: the section is one item of a layout this plugin
+ * draws — among the editor's fields, above the catalog table, inside the
+ * import dialog — and a wrapper would add a gap the page already spaces.
+ */
+export declare function registerCommerceZones(): void;

package/src/lib/components/console/product-zones.js

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { definePluginZone, registerPluginZone } from "@aglyn/aglyn/plugin-manager/plugin-zones";
+import { BUNDLE_ID } from "../../constants/bundle-common.js";
+export const PRODUCT_EDITOR_ZONE = definePluginZone('productEditor');
+export const PRODUCTS_HUB_ZONE = definePluginZone('productsHub');
+export const PRODUCT_IMPORT_ZONE = definePluginZone('productImport');
+/**
+ * Declares the three zones, from the console registrar. The ids are the ones
+ * widgets have always registered under, so a widget written for them keeps
+ * working. Each is `bare`: the section is one item of a layout this plugin
+ * draws — among the editor's fields, above the catalog table, inside the
+ * import dialog — and a wrapper would add a gap the page already spaces.
+ */ export function registerCommerceZones() {
+    const owner = {
+        pluginId: BUNDLE_ID
+    };
+    registerPluginZone({
+        zone: PRODUCT_EDITOR_ZONE,
+        label: 'Product editor',
+        surface: 'console',
+        layout: 'bare',
+        description: 'Under a product’s description, tags and categories in the product editor. A widget here proposes copy for the fields through `proposeValues`, staged as unsaved edits; Save product is the write.'
+    }, owner);
+    registerPluginZone({
+        zone: PRODUCTS_HUB_ZONE,
+        label: 'Products hub',
+        surface: 'console',
+        layout: 'bare',
+        description: 'Above the catalog table on the Products page. A widget here proposes copy, draft products, categories and switched-off discounts, and asks the hub to write them; every write is the hub’s, with its allowance and slug checks.'
+    }, owner);
+    registerPluginZone({
+        zone: PRODUCT_IMPORT_ZONE,
+        label: 'Product CSV import',
+        surface: 'console',
+        layout: 'bare',
+        description: 'Inside the CSV import dialog. A widget here sets options for what happens to the imported products once they land; the hub hands them to `productsHub` with the ids the import created.'
+    }, owner);
+}
+
+//# sourceMappingURL=product-zones.js.map

package/src/lib/components/console/product-zones.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/plugins/commerce/src/lib/components/console/product-zones.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginZone,\n  registerPluginZone,\n} from '@aglyn/aglyn/plugin-manager/plugin-zones'\nimport { BUNDLE_ID } from '../../constants/bundle-common'\n\n/**\n * The zones this plugin hosts on its product surfaces (AGL-2916): the product\n * editor, the products hub and the CSV import dialog.\n *\n * Each is drawn through the shell's renderer (`useConsoleWidgetSlot`), so a\n * widget there passes the same enablement, entitlement and permission gates as\n * one on a console page. The props are this plugin's words for its catalog,\n * declared on the zone's token; a widget from another plugin restates the\n * shape it reads rather than importing this package. A widget proposes and\n * never writes: every write is this plugin's, with the guards it carries.\n */\n\n/** A product type, as the commerce catalog names it. */\nexport type ConsoleProductType = 'physical' | 'digital' | 'service'\n\n/** A product option axis: its name and the values a shopper picks from. */\nexport interface ConsoleProductOption {\n  name: string\n  values: string[]\n}\n\n/** A product as the commerce editor holds it: saved, or staged and unsaved. */\nexport interface ConsoleProductDraft {\n  /** `null` for a product nobody has saved yet. */\n  id: string | null\n  name: string\n  type: ConsoleProductType\n  description: string\n  tags: string[]\n  categoryIds: string[]\n  options: ConsoleProductOption[]\n  /** The product's media, in order; the first is the photo the storefront leads with. */\n  mediaUrls: string[]\n  seoTitle: string\n  seoDescription: string\n}\n\n/**\n * Copy a widget proposes for one product. A field left out is left alone;\n * `optionNames` renames the product's options in order, keeping every\n * variant, and is ignored unless it names each option once.\n */\nexport interface ConsoleProductCopyValues {\n  description?: string\n  tags?: string[]\n  categoryIds?: string[]\n  optionNames?: string[]\n  seoTitle?: string\n  seoDescription?: string\n}\n\n/**\n * What the `productEditor` zone hands each widget: the product as the editor\n * holds it, and `proposeValues`, which stages copy in the editor as unsaved\n * edits. The zone sits under the product's description, tags and categories,\n * as the editor's search listing hosts `seoFields`. Save product is the\n * write, with the guards it carries.\n */\nexport interface ConsoleProductEditorZoneProps {\n  hostId: string\n  /** The org the page names; `undefined` where the host does not know it. */\n  orgId: string | undefined\n  product: ConsoleProductDraft\n  /** The site's categories, as the editor's picker lists them. */\n  categories: ReadonlyArray<{ id: string; name: string }>\n  /**\n   * Stages `values` in the editor as unsaved edits under `key`. Save product\n   * is what stores them; a widget never writes the product itself.\n   */\n  proposeValues: (values: ConsoleProductCopyValues, key: string) => void\n}\n\n/** A catalog row as the products hub holds it. */\nexport interface ConsoleProductSummary {\n  id: string\n  name: string\n  status: 'draft' | 'active' | 'archived'\n  /** Whether a variant of the product has no price yet. */\n  priceMissing: boolean\n  /** Whether the product has a photo. */\n  hasPhoto: boolean\n}\n\n/** A new product a widget asks the hub to create, always as a draft with no price. */\nexport interface ConsoleProposedProduct {\n  name: string\n  type: ConsoleProductType\n  description: string\n  tags: string[]\n  options: ConsoleProductOption[]\n  seoTitle: string\n  seoDescription: string\n}\n\n/** A discount a widget asks the hub to create, always switched off. */\nexport interface ConsoleProposedDiscount {\n  name: string\n  /** The code a shopper types, or `null` for a discount that applies on its own. */\n  code: string | null\n  kind: 'percent' | 'fixed' | 'free_shipping'\n  valuePct: number | null\n  valueCents: number | null\n  minSubtotalCents: number | null\n}\n\n/**\n * What the `productsHub` zone hands each widget: the catalog rows the hub\n * holds, the products its latest import created, and the hub's own writes a\n * widget may ask it to make — copy onto saved products, new draft products,\n * categories and switched-off discounts. The zone sits above the catalog\n * table. Each write is the hub's, with its seed, allowance and slug checks; a\n * widget writes nothing itself. Every write resolves once it is stored and\n * throws with a message a person can act on when the hub refuses it: an\n * allowance the plan has no room for, a product that is gone.\n *\n * The creates are safe to ask twice: a product or a category named like one\n * the site has, and a discount with the code (or, with no code, the name) of\n * one the site has, are passed over, so a proposal applied again, by anyone,\n * creates nothing it already created.\n */\nexport interface ConsoleProductsHubZoneProps {\n  hostId: string\n  /** The org the page names; `undefined` where the host does not know it. */\n  orgId: string | undefined\n  /** The catalog rows the hub holds, in its order. */\n  products: readonly ConsoleProductSummary[]\n  /**\n   * The products the hub's latest CSV import created in this visit, and the\n   * options the `productImport` zone set for them; `null` before any import.\n   * `key` is new for each import.\n   */\n  lastImport: {\n    key: string\n    productIds: readonly string[]\n    options: Readonly<Record<string, boolean>>\n  } | null\n  /** Writes copy onto a saved product, read fresh from the store. */\n  applyProductCopy: (productId: string, values: ConsoleProductCopyValues) => Promise<void>\n  /** Creates each product as a draft with no price, and resolves with the ids it created. */\n  createProductDrafts: (products: readonly ConsoleProposedProduct[]) => Promise<string[]>\n  /** Creates categories by name, and resolves with how many it created. */\n  createCategories: (names: readonly string[]) => Promise<number>\n  /** Creates each discount switched off, and resolves with how many it created. */\n  createDiscountDrafts: (discounts: readonly ConsoleProposedDiscount[]) => Promise<number>\n}\n\n/**\n * What the `productImport` zone hands each widget, inside the CSV import\n * dialog: how many products the import creates, and options a widget sets\n * for what happens to them once they land. The hub hands the options, with\n * the ids of the products the import created, to `productsHub` as its\n * `lastImport`.\n */\nexport interface ConsoleProductImportZoneProps {\n  hostId: string\n  /** The org the page names; `undefined` where the host does not know it. */\n  orgId: string | undefined\n  /** How many products the import creates. */\n  count: number\n  /** The options set for this import, by key. */\n  options: Readonly<Record<string, boolean>>\n  /** Sets one option; the hub carries it to `productsHub` with what the import created. */\n  setOption: (key: string, on: boolean) => void\n}\n\nexport const PRODUCT_EDITOR_ZONE =\n  definePluginZone<ConsoleProductEditorZoneProps>('productEditor')\n\nexport const PRODUCTS_HUB_ZONE =\n  definePluginZone<ConsoleProductsHubZoneProps>('productsHub')\n\nexport const PRODUCT_IMPORT_ZONE =\n  definePluginZone<ConsoleProductImportZoneProps>('productImport')\n\n/**\n * Declares the three zones, from the console registrar. The ids are the ones\n * widgets have always registered under, so a widget written for them keeps\n * working. Each is `bare`: the section is one item of a layout this plugin\n * draws — among the editor's fields, above the catalog table, inside the\n * import dialog — and a wrapper would add a gap the page already spaces.\n */\nexport function registerCommerceZones(): void {\n  const owner = { pluginId: BUNDLE_ID }\n  registerPluginZone(\n    {\n      zone: PRODUCT_EDITOR_ZONE,\n      label: 'Product editor',\n      surface: 'console',\n      layout: 'bare',\n      description:\n        'Under a product’s description, tags and categories in the product editor. A widget here proposes copy for the fields through `proposeValues`, staged as unsaved edits; Save product is the write.',\n    },\n    owner,\n  )\n  registerPluginZone(\n    {\n      zone: PRODUCTS_HUB_ZONE,\n      label: 'Products hub',\n      surface: 'console',\n      layout: 'bare',\n      description:\n        'Above the catalog table on the Products page. A widget here proposes copy, draft products, categories and switched-off discounts, and asks the hub to write them; every write is the hub’s, with its allowance and slug checks.',\n    },\n    owner,\n  )\n  registerPluginZone(\n    {\n      zone: PRODUCT_IMPORT_ZONE,\n      label: 'Product CSV import',\n      surface: 'console',\n      layout: 'bare',\n      description:\n        'Inside the CSV import dialog. A widget here sets options for what happens to the imported products once they land; the hub hands them to `productsHub` with the ids the import created.',\n    },\n    owner,\n  )\n}\n"],"names":["definePluginZone","registerPluginZone","BUNDLE_ID","PRODUCT_EDITOR_ZONE","PRODUCTS_HUB_ZONE","PRODUCT_IMPORT_ZONE","registerCommerceZones","owner","pluginId","zone","label","surface","layout","description"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,gBAAgB,EAChBC,kBAAkB,QACb,2CAA0C;AACjD,SAASC,SAAS,QAAQ,mCAA+B;AAuKzD,OAAO,MAAMC,sBACXH,iBAAgD,iBAAgB;AAElE,OAAO,MAAMI,oBACXJ,iBAA8C,eAAc;AAE9D,OAAO,MAAMK,sBACXL,iBAAgD,iBAAgB;AAElE;;;;;;CAMC,GACD,OAAO,SAASM;IACd,MAAMC,QAAQ;QAAEC,UAAUN;IAAU;IACpCD,mBACE;QACEQ,MAAMN;QACNO,OAAO;QACPC,SAAS;QACTC,QAAQ;QACRC,aACE;IACJ,GACAN;IAEFN,mBACE;QACEQ,MAAML;QACNM,OAAO;QACPC,SAAS;QACTC,QAAQ;QACRC,aACE;IACJ,GACAN;IAEFN,mBACE;QACEQ,MAAMJ;QACNK,OAAO;QACPC,SAAS;QACTC,QAAQ;QACRC,aACE;IACJ,GACAN;AAEJ"}

package/src/lib/components/console/products-hub-card.component.js

@@ -46,6 +46,7 @@ import { productCollectionFields, readSmartCollections } from "./smart-collectio
 import ProductsHubZone from "./products-hub-zone.component.js";
 import { pluginDocsHelp } from "@aglyn/aglyn";
 import { useConsoleWidgetSlot } from "@aglyn/aglyn/app-utils/console-widget-slot-context";
+import { PRODUCT_IMPORT_ZONE } from "./product-zones.js";
 /** Products read per request of the CSV export's walk. */ const EXPORT_PAGE = 500;
 /**
  * The most products one CSV export writes (AGL-3321).
@@ -913,7 +914,7 @@ const STATUS_COLOR = {
                             }
                         },
                         noRowsLabel: filtering ? 'No products match these filters' : 'No products yet',
-                        noRowsDescription: filtering ? undefined : 'Build your catalog: add a product, then drop commerce ' + 'blocks on any screen in Besigner.'
+                        noRowsDescription: filtering ? undefined : 'Build your catalog: add a product, then drop commerce ' + 'blocks on any page in Besigner.'
                     }),
                     products.length === 0 && page === 0 && productsStatus !== 'loading' ? null : /* The count line is the PAGE's. `hasMore` is a fact from the probe
              row; the site's total is `productCount` above, which counts the
@@ -1111,7 +1112,7 @@ const STATUS_COLOR = {
                                 ]
                             }) : null,
                             WidgetSlot && (importing == null ? void 0 : (_importing_parsed = importing.parsed) == null ? void 0 : _importing_parsed.products.length) ? /*#__PURE__*/ _jsx(WidgetSlot, {
-                                slot: "productImport",
+                                slot: PRODUCT_IMPORT_ZONE.id,
                                 hostId: hostId,
                                 orgId: undefined,
                                 count: importing.parsed.products.length,