Skip to content

feat(products): add the product management elements - #297

Draft
brettflorio wants to merge 23 commits into
mainfrom
feat/foxy-products
Draft

brettflorio wants to merge 23 commits into
mainfrom
feat/foxy-products

Conversation

@brettflorio

Copy link
Copy Markdown
Contributor

Adds the elements for managing a store's products: the product form (general fields, options and variants, modifiers, images, stock rules, inventory, logs, organization and inheritance), the product list, inventory and collection form, and the product card. The form previews its description through a description-preview slot and event, shows brand, GTIN and MPN, and explains fields with help tips. Prices use each currency's own decimals.

Proof: web-test-runner groups, all passing: foxy-product-form, foxy-product-card (25), foxy-product-list (53), utils (91). tsc --noEmit is clean.

Check by hand (Storybook or a host app with a products API):

  • Open a product from a template: empty fields show the inherited value as a placeholder.
  • Open Preview beside the description and type: a description-preview event follows each pause in typing.
  • Show a yen price and a dinar price: no .00 on the yen, three decimals on the dinar.

Risks:

  • The user invitation "read" and "write" presets now include products, which needs an API that accepts the products scopes.
  • Merging to main publishes a release.

🤖 Generated with Claude Code

Brett Florio and others added 23 commits November 18, 2026 13:49
Foundation for the Foxy Products admin UI. Defines the type graph and
seeds the demo hAPI so subsequent units (cards, forms, admin pages) can
develop and Storybook against working data.

Types — `src/elements/public/Product{Card,Form,VariantCard,CategoryCard,
CategoryForm,TagCard,TagForm,EventCard}/types.ts`:
  - Inline `Graph` definitions for Product, Products, ProductCategory,
    ProductCategories, ProductTag, ProductTags, ProductStockRule,
    ProductStockRules, ProductEvent, ProductEvents — modelled on the
    Passkey/Passkeys precedent (the SDK doesn't ship product Rels yet).
  - `Data` re-exports between sibling Card/Form folders so consumers
    only import from one place per resource. Variants reuse `Product`.
  - `ProductDefinition` interface captures the JSON `definition` blob
    shape from `views/resources/product.twig` (name, price, list_price,
    prices, description, images, brand, gtin, mpn, attributes, options,
    meta_*, weight, category_code, subscription_*, translations).

Mock server — `src/server/hapi/{defaults,links,createDataset}.ts`:
  - Five new collection factories (`products`, `product_categories`,
    `product_tags`, `product_stock_rules`, `product_events`) so POST
    creates valid resources with sensible defaults.
  - Link generators for each, plus `fx:products` and
    `fx:product_categories` on `stores`. Conditional `fx:parent_product`,
    `fx:product_category`, `fx:parent_category` are emitted only when
    the FK is set.
  - Seed data for store 0: 4 categories (Apparel/Shirts, Accessories
    nested under All Products), 5 products (1 standalone, 1 parent +
    2 variants, 1 template), 3 tags, 1 stock rule (variant decrements
    parent stock), 3 events (incl. an auto-promotion `product_type`
    change record).

`tsc --noEmit` clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Catalog list-row component for the Foxy Products admin UI.

<foxy-product-card href="…/products/0"></foxy-product-card> renders:
- thumbnail (from definition.images[0].src) with a fallback placeholder
- product name (definition.name, falls back to SKU)
- SKU
- product type badge (standalone | parent | variant | template)
- price (from definition.price; optionally formatted with a currency
  attribute via foxy-i18n's price formatter)
- stock indicator: green / amber / red / gray dot for
  in_stock / low_stock / out_of_stock / untracked. Threshold is 5,
  configurable via the `low-stock-threshold` attribute.
- variant count badge (only for `parent` products with variant_count > 0)

Implementation extends ConfigurableMixin(TranslatableMixin(InternalCard,
'product-card')), following the AppliedCouponCodeCard precedent. Each
visible element carries a `data-testid` so tests can target by role
without coupling to layout.

Tests: 18 passed (custom-element registration + InternalCard inheritance
+ name/SKU/badge/price rendering + stock-state matrix + variant-count
visibility rules). Type-check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The main create/edit form for Foxy Products plus the minimal Tag
card/form that ProductForm's tags section uses inline.

<foxy-product-form>:
- Extends TranslatableMixin(InternalForm, 'product-form').
- v8n: SKU required + max 255, definition.name required, definition.price >= 0
  when set. Null/undefined price is allowed so users can clear it.
- Properties: `product-categories` URL forwarded to the category picker.
- Core "general" summary control: name (property="definition.name"),
  SKU (top-level), price (property="definition.price", min 0),
  description (property="definition.description"), category picker
  (property="category_id", item="foxy-product-category-card", arrives in Unit 7).
- "stock" summary: stock-level number control (property="stock_level"),
  null = untracked, 0 = out of stock.
- Tags: InternalAsyncListControl bound to fx:product_tags, item
  ProductTagCard, form ProductTagForm.
- Variant mode detection: when product_type === 'variant', shows an
  inheritance note paragraph and overrides _sendGet() to chain a
  super._fetch on _links['fx:parent_product'] (mirrors ItemForm's
  chained-fetch pattern). Parent values are passed as `placeholder`
  attributes on the relevant controls so empty variant fields display
  what they'd inherit.
- Section placeholders for Units 6/8/9 (variants, advanced, stock-rules,
  events) rendered as empty data-testid'd divs so the structural
  contract is testable now and Units 6/8/9 swap them for real content
  later. Hidden by default on unsaved products via hiddenSelector.

<foxy-product-tag-card>: minimal chip-style card displaying `tag`.
<foxy-product-tag-form>: minimal form with one text control bound to
`tag`, v8n: required + max 255.

Tests:
- ProductTagCard: 6 passed (registration, NS, InternalCard inheritance,
  tag rendering).
- ProductTagForm: 10 passed (registration, NS, form/Nucleon inheritance,
  v8n required/too_long/valid, control rendering).
- ProductForm: 27 passed (registration of all 6 internal controls and 2
  Tag elements, NS, Form/Nucleon inheritance, v8n matrix incl.
  null-price-OK, structural placeholders, inheritance-note visibility,
  property-binding attributes for definition.name/price and bare SKU,
  productCategories attribute forwarding, hiddenSelector for
  variants/tags/events/stock-rules in unsaved/variant modes).

Type-check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three new elements plus a small types fix.

<foxy-product-category-card>
- Two-line layout via TwoLineCard: name (title), slug (subtitle).
- Used by ProductForm's category picker and the tree control's nodes.

<foxy-product-category-form>
- TranslatableMixin(InternalForm, 'product-category-form').
- v8n: name required + max 255, slug required + max 255 + kebab-case
  pattern (^[a-z0-9]+(?:-[a-z0-9]+)*$). Path is server-computed and
  read-only.
- Core summary: name, slug, parent picker (resource picker bound to
  the same product_categories collection, item="foxy-product-category-card",
  property="parent_id"), sort_order.

<foxy-internal-product-category-tree-control>
- Novel control under ProductCategoryForm/internal/. Extends
  InternalControl (display/navigation, not a form field).
- Receives `first` (collection URL) and optional `limit` (default 300)
  and `refresh` (cache-buster). Fetches via foxy-nucleon, builds a
  tree client-side from parent_id, sorts siblings by sort_order then
  name, renders as nested <details> blocks.
- Action buttons (Add subcategory / Edit / Delete / Add root) dispatch
  three CustomEvents (`productcategory:create` / `:edit` / `:delete`)
  with detail.{parent_id|id} so the host page wires actions; the
  control itself stays display-only and is re-fetched by bumping
  `refresh` after a mutation.

Types fix: added `id: number` to props on Product, ProductCategory,
ProductTag, ProductStockRule, and ProductEvent so `data.id` is
typed (matches Customer's pattern; Resource<T> expects id in props
when needed). The tree control needs this for action-event payloads.

Tests: 5 (Card) + 29 (Form + Tree) = 34 total, 0 failing.
- Card: registration, NS, TwoLineCard/Nucleon inheritance, name+slug rendering.
- Form: registration of all internal controls + the tree control + the
  Card; NS; Form/Nucleon inheritance; v8n matrix incl. kebab-case
  validation; field/picker rendering; productCategories attribute
  forwarding; property bindings.
- Tree: registration + InternalControl inheritance; empty-state
  placeholder + add-root button; live-fetch tree build verifies
  4 seeded categories and 1 top-level root (All Products); each of
  the four action buttons dispatches the right CustomEvent with the
  right detail payload.

Type-check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The API takes images as {src, alt, width, height}, the shape Shopify and
WooCommerce export, so alt text survives an import.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iants

Images upload straight to storage when picked, through the
fx:create_upload_url link the admin backend adds to a saved product,
and each gets alt text, prefilled as "Image of <name>" for the merchant
to replace. The description is a text area where Enter starts a new
line. Variants list under their parent and are created there. The
product card shows a variant's inherited name and price.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gory

The form's sections and lists read label and helper_text, and the
category picker needs the category's href, not category_id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…el list buttons

The tags and variants lists, their dialogs and the form buttons read
pagination.*, pagination.card.*, dialog.<form namespace>.* and *.caption
in this version of the elements; the variant dialog holds a whole copy of
the product form's strings, minus the variants list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nts to logs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CHROME_PATH still wins, and the dev container's /usr/bin/chromium comes
first; without any of them, puppeteer's own downloaded browser runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… add-to-cart link in the product form

ProductForm gains a list price, a template picker and a Product or
Template choice when creating, a properties editor, a stock rules list
(new foxy-product-stock-rule-card and -form), a template's own products,
and a copyable add-to-cart link for products that can be added. Empty
fields show what the product inherits from its parent or template.
ProductCard marks products that use a template.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… variants and build add-to-cart links

Options are offered on standalone and parent products only; a variant
picks its values from its parent's options instead. Saving options that
drop a value or an option deletes the variants using it, so the form
holds the save until the merchant confirms that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t form out in sections

foxy-product-list and foxy-product-inventory load every product of the
store and sort, search and group in the browser: the API can neither
filter nor order by name, and a products collection can't embed variants.

A variant's price and stock edited in the form's table are saved by the
form's submit(), one PATCH per variant, before the product itself.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nd pick categories and collections from a searchable list

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…d logs, thumbnails and list columns

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… group a product's organization, and edit collections' item category

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion as a table

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A yen price no longer shows .00 and a dinar price keeps its third decimal,
in the product list and on product cards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… and explain fields with help tips

The preview is a collapsible panel beside the description. The host draws
it, in the description-preview slot, and hears a description-preview event
with the unsaved product a moment after each change. The panel remembers
whether it was left open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…re id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.


Brett Florio seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You have signed the CLA already but the status is still pending? Let us recheck it.

1 similar comment
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.


Brett Florio seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants