@stapel/categories-react 0.1.0

package/src/default/CategoryTreePane.tsx

@@ -0,0 +1,134 @@
+/**
+ * `<CategoryTreePane>` — one level of the catalogue as a list of links.
+ *
+ * The four arms of `matchList` are the point of this file, not decoration:
+ * "still syncing", "the sync failed", "this category has no sub-categories"
+ * and "here they are" are four different sentences, and the third is the one a
+ * leaf category legitimately gets. Collapsing any two is the incident
+ * `@stapel/core`'s `loadState.ts` was written for.
+ *
+ * A fifth condition rides alongside them: `truncated`. The sync walk hit its
+ * page budget, so what is on screen is a PARTIAL catalogue — which is neither
+ * an empty one nor a failed one, and gets its own line rather than being
+ * silently indistinguishable from a complete tree.
+ */
+import type { ReactElement } from "react";
+import { Alert, Badge, Empty, Flex, List, Spin, Typography } from "antd";
+import { matchList, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import { categoryLabel, renderCategoryLabel } from "../catalog/labels.js";
+import type { CategoryNode } from "../catalog/tree.js";
+import { CategoryTree } from "../headless/CategoryTree.js";
+import { CATEGORIES_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { CategoriesSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface CategoryTreePaneProps extends ThemeModeProp {
+  /** Render this category's children. Omitted renders the roots. */
+  readonly parentId?: number | null;
+  /** Render the children of the category at this slug (the `/c/:slug` page). */
+  readonly slug?: string;
+  /** Path prefix for a row's link. Default `/c`. */
+  readonly basePath?: string;
+  /** Heading above the list. Omitted renders no heading. */
+  readonly titleKey?: string;
+}
+
+export function CategoryTreePane(props: CategoryTreePaneProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const base = props.basePath ?? "/c";
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <CategoryTree
+        {...(props.parentId !== undefined ? { parentId: props.parentId } : {})}
+        {...(props.slug !== undefined ? { slug: props.slug } : {})}
+      >
+        {(bag) => (
+          <Flex vertical gap={8} data-testid="categories-tree">
+            {props.titleKey !== undefined ? (
+              <Typography.Title level={5} style={{ margin: 0 }}>
+                {t(props.titleKey)}
+              </Typography.Title>
+            ) : null}
+
+            {bag.truncated ? (
+              <Alert
+                type="warning"
+                showIcon
+                data-testid="categories-tree-truncated"
+                message={t(CATEGORIES_I18N_KEYS.catalogTruncated)}
+              />
+            ) : null}
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex justify="center" style={{ padding: 16 }}>
+                  <Spin data-testid="categories-tree-loading" />
+                </Flex>
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="categories-tree-failed"
+                  error={{
+                    ...describe(toFlowError(error)),
+                    message: t(CATEGORIES_I18N_KEYS.catalogLoadFailed),
+                  }}
+                />
+              ),
+              empty: () => (
+                <Empty
+                  data-testid="categories-tree-empty"
+                  description={t(
+                    bag.current === null
+                      ? CATEGORIES_I18N_KEYS.catalogEmpty
+                      : CATEGORIES_I18N_KEYS.categoryNoSubcategories
+                  )}
+                />
+              ),
+              ready: (nodes) => (
+                <List<CategoryNode>
+                  data-testid="categories-tree-list"
+                  size="small"
+                  dataSource={[...nodes]}
+                  renderItem={(node) => (
+                    <List.Item key={node.id} data-category-id={node.id}>
+                      <Flex
+                        justify="space-between"
+                        align="center"
+                        gap={8}
+                        style={{ width: "100%" }}
+                      >
+                        <Typography.Link
+                          href={`${base}/${node.category.slug}`}
+                          data-category-slug={node.category.slug}
+                        >
+                          {renderCategoryLabel(
+                            categoryLabel(node.category),
+                            t
+                          )}
+                        </Typography.Link>
+                        {node.children.length > 0 ? (
+                          <Badge
+                            count={node.children.length}
+                            color="blue"
+                            title={t(
+                              CATEGORIES_I18N_KEYS.categorySubcategories
+                            )}
+                          />
+                        ) : null}
+                      </Flex>
+                    </List.Item>
+                  )}
+                />
+              ),
+            })}
+          </Flex>
+        )}
+      </CategoryTree>
+    </CategoriesSkinTheme>
+  );
+}

package/src/default/ErrorAlert.tsx

@@ -0,0 +1,46 @@
+/**
+ * The one error surface this pair's default skin renders, so the split copy
+ * core produces reaches a screen the same way everywhere (mirrors the
+ * docs/notifications/workspaces etalon).
+ *
+ * Core's `describeFlowError` splits a failure into the sentence a person
+ * reads and the technical detail a support agent quotes (owner report
+ * 2026-08-09: the status used to be spliced into the sentence, ending in a
+ * bare `" (500)"`). The split only helps if a skin renders both halves at
+ * their own weights: `message` at normal weight, `detail` muted and small.
+ *
+ * `undefined` in — including a `detail` core left `undefined` because there
+ * was nothing worth quoting — renders nothing rather than an empty line.
+ */
+import { Alert, Typography } from "antd";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import type { FlowErrorDisplay } from "@stapel/core";
+
+export function ErrorAlert(props: {
+  error: FlowErrorDisplay | undefined;
+  style?: CSSProperties | undefined;
+  testId?: string | undefined;
+  action?: ReactNode;
+}): ReactElement | null {
+  const { error } = props;
+  if (!error) return null;
+  return (
+    <Alert
+      type="error"
+      showIcon
+      {...(props.style ? { style: props.style } : {})}
+      {...(props.testId ? { "data-testid": props.testId } : {})}
+      {...(props.action ? { action: props.action } : {})}
+      message={error.message}
+      {...(error.detail
+        ? {
+            description: (
+              <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                {error.detail}
+              </Typography.Text>
+            ),
+          }
+        : {})}
+    />
+  );
+}

package/src/default/index.ts

@@ -0,0 +1,36 @@
+/**
+ * `@stapel/categories-react/default` — the antd skin over the headless pair.
+ *
+ * A separate entry point (the convention every pair's `/default` follows) so a
+ * host rendering its own catalogue chrome never pulls `antd` into its bundle.
+ * The main entry has no visual opinion at all and no import path from it
+ * reaches this directory — size-limit and the bundle-purity test are the
+ * teeth on that.
+ *
+ * ```tsx
+ * import { createCategoriesRuntime, CategoriesProvider } from "@stapel/categories-react";
+ * import { CatalogPage, CategoryPage } from "@stapel/categories-react/default";
+ * ```
+ *
+ * `CategoryPage` takes `renderListings` — the half of `/c/:slug` that belongs
+ * to `@stapel/search-react`, handed in by the container rather than imported
+ * across the L2 layer.
+ */
+export { CatalogPage } from "./CatalogPage.js";
+export type { CatalogPageProps } from "./CatalogPage.js";
+export { CategoryPage } from "./CategoryPage.js";
+export type { CategoryPageProps } from "./CategoryPage.js";
+export { CategoryTreePane } from "./CategoryTreePane.js";
+export type { CategoryTreePaneProps } from "./CategoryTreePane.js";
+export { CategoryBreadcrumbsBar } from "./CategoryBreadcrumbsBar.js";
+export type { CategoryBreadcrumbsBarProps } from "./CategoryBreadcrumbsBar.js";
+export { CategoryCarouselStrip } from "./CategoryCarouselStrip.js";
+export type { CategoryCarouselStripProps } from "./CategoryCarouselStrip.js";
+export { CategoryPickerField } from "./CategoryPickerField.js";
+export type { CategoryPickerFieldProps } from "./CategoryPickerField.js";
+export { CategoryFeatureList } from "./CategoryFeatureList.js";
+export type { CategoryFeatureListProps } from "./CategoryFeatureList.js";
+export { CategoriesSkinTheme } from "./theme.js";
+export type { CategoriesSkinThemeProps } from "./theme.js";
+export { ErrorAlert } from "./ErrorAlert.js";
+export type { ThemeModeProp } from "./types.js";

package/src/default/theme.tsx

@@ -0,0 +1,67 @@
+/**
+ * The default skin's INTERNAL theme provider — every `/default` surface wraps
+ * itself in this, so the skin is readable no matter what the host supplies
+ * (tracker #26: a skin set with no internal provider once inherited a theme
+ * bridge serving light-mode values inside a dark document — text on
+ * background at 1.00:1). The theme derives from `@stapel/tokens` via
+ * `@stapel/tokens-antd`'s `toAntdThemeConfig(mode)`; `mode` defaults to what
+ * the HOST's document declares (`resolveThemeMode()` — the `data-theme`
+ * attribute `tokens.css` keys its dark block on), never to a hardcoded side.
+ *
+ * This is also what "override styles" means for this pair: a storefront
+ * retheming through the §68 token JSON regenerates its `--stapel-*` custom
+ * properties and the result page follows with zero code — a far better deal
+ * than a prop-per-colour API, and the reason the skin has none.
+ */
+import { useMemo } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { ConfigProvider } from "antd";
+import {
+  resolveThemeMode,
+  toAntdTheme,
+  toAntdThemeConfig,
+} from "@stapel/tokens-antd";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+export interface CategoriesSkinThemeProps {
+  /**
+   * Light or dark. Defaults to the mode the host's document declares
+   * (`resolveThemeMode()`). Pass explicitly to pin a side.
+   */
+  readonly mode?: ThemeMode;
+  /** Extra styles merged onto the themed root element (layout only — colors
+   * come from the mode). */
+  readonly style?: CSSProperties;
+  readonly children: ReactNode;
+}
+
+/**
+ * `<CategoriesSkinTheme/>` — the self-theming wrapper of
+ * `@stapel/categories-react/default`. Standalone use is supported (wrap any
+ * composition of the skin's parts once); the shipped surfaces
+ * (`CatalogPage`, `CategoryPage`, `CategoryTreePane`, `CategoryCarouselStrip`,
+ * `CategoryPickerField`, `CategoryFeatureList`, `CategoryBreadcrumbsBar`)
+ * each already wrap themselves, and nested antd
+ * `ConfigProvider`s merge, so composing them under one `CategoriesSkinTheme`
+ * stays correct.
+ */
+export function CategoriesSkinTheme(props: CategoriesSkinThemeProps): ReactElement {
+  const mode = props.mode ?? resolveThemeMode();
+  const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
+  const token = useMemo(() => toAntdTheme(mode), [mode]);
+  return (
+    <ConfigProvider theme={theme}>
+      <div
+        data-categories-skin-root
+        data-categories-skin-mode={mode}
+        style={{
+          color: token.colorText,
+          backgroundColor: token.colorBgContainer,
+          ...props.style,
+        }}
+      >
+        {props.children}
+      </div>
+    </ConfigProvider>
+  );
+}

package/src/default/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Small shared types for the `/default` skin — kept in one place so every
+ * surface takes the same `mode` prop and re-exports the same error dialect.
+ */
+export type { FlowError } from "@stapel/core";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+/** Every `/default` surface accepts a theme mode; absent means "whatever the
+ * host document declares" (`resolveThemeMode()`), never a hardcoded side. */
+export interface ThemeModeProp {
+  readonly mode?: ThemeMode;
+}

package/src/headless/CategoriesProvider.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { ModuleProvider } from "../model/context.js";
+import type { CategoriesRuntime } from "../model/runtime.js";
+
+/**
+ * Provides the wired {@link CategoriesRuntime} to every categories hook and
+ * headless component below it. Bring your own visual shell — this component
+ * renders nothing of its own. (Core's `createModuleContext` provider, bound to
+ * this pair — slim wave §21/S2.)
+ *
+ * ```tsx
+ * const runtime = createCategoriesRuntime({ baseUrl: "/categories/api/v1/" });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <CategoriesProvider runtime={runtime}>{app}</CategoriesProvider>
+ * ```
+ */
+export const CategoriesProvider: (props: {
+  runtime: CategoriesRuntime;
+  children: ReactNode;
+}) => ReactElement = ModuleProvider;

package/src/headless/CategoryBreadcrumbs.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import { categoryBreadcrumbs, resolveCategorySlug } from "../catalog/tree.js";
+import type { CategoryNode } from "../catalog/tree.js";
+import { categoryLabel } from "../catalog/labels.js";
+import type { CategoryLabel } from "../catalog/labels.js";
+import { useCategoryCatalog } from "../model/queries.js";
+import type { UseCategoryCatalogOptions } from "../model/queries.js";
+
+/** One crumb: the node, and how its caption must be rendered. */
+export interface CategoryCrumb {
+  readonly node: CategoryNode;
+  /** `kind: "key"` → run `value` through the host's `t`. See
+   * `catalog/labels.ts` — names on the wire are translation keys. */
+  readonly label: CategoryLabel;
+  /** `true` for the last crumb — the page you are on. */
+  readonly isCurrent: boolean;
+}
+
+export interface CategoryBreadcrumbsBag {
+  /**
+   * Root → current, inclusive. `empty` means the selected category IS a root
+   * (there is nothing above it), which is a different thing from a catalogue
+   * that has not loaded and from a slug that does not exist.
+   */
+  readonly state: LoadState<readonly CategoryCrumb[]>;
+  readonly unknownSlug: boolean;
+  refetch(): void;
+}
+
+export interface CategoryBreadcrumbsProps extends UseCategoryCatalogOptions {
+  slug?: string;
+  categoryId?: number | null;
+  children: (bag: CategoryBreadcrumbsBag) => ReactNode;
+}
+
+/**
+ * The ancestry of the current category, as data.
+ *
+ * Walks the BUILT index rather than `tn_ancestors_pks`: a crumb must name a
+ * category the visitor can actually open, and the built index is what the
+ * visitor is being shown. The server's own column is exposed separately
+ * (`categoryAncestorIds`) and the two are cross-checked in the suite, so a
+ * divergence is a red test rather than a link to nowhere.
+ */
+export function CategoryBreadcrumbs(
+  props: CategoryBreadcrumbsProps
+): ReactNode {
+  const { slug, categoryId, children, ...catalogOptions } = props;
+  const query = useCategoryCatalog(catalogOptions);
+  const catalog = loadStateFromQuery(query);
+  const index = catalog.status === "ready" ? catalog.data.index : null;
+
+  let current: CategoryNode | null = null;
+  if (index !== null) {
+    if (slug !== undefined) current = resolveCategorySlug(index, slug) ?? null;
+    else if (categoryId !== null && categoryId !== undefined) {
+      current = index.byId.get(categoryId) ?? null;
+    }
+  }
+
+  return children({
+    state: mapLoad(catalog, (data) => {
+      const path = categoryBreadcrumbs(data.index, current?.id);
+      return path.map((node, i) => ({
+        node,
+        label: categoryLabel(node.category),
+        isCurrent: i === path.length - 1,
+      }));
+    }),
+    unknownSlug:
+      catalog.status === "ready" && slug !== undefined && current === null,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/headless/CategoryCarousel.tsx

@@ -0,0 +1,80 @@
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { Category } from "../api/types.js";
+import { categoryLabel } from "../catalog/labels.js";
+import type { CategoryLabel } from "../catalog/labels.js";
+import { useCategoryCarousel } from "../model/queries.js";
+
+/** One carousel tile. */
+export interface CarouselEntry {
+  readonly category: Category;
+  readonly label: CategoryLabel;
+  /**
+   * The tile's icon reference — `carousel_icon`, falling back to
+   * `catalog_icon`. Both are OPAQUE STRINGS, deliberately decoupled from
+   * stapel-cdn ("an opaque string, resolved by the host if at all",
+   * `models.py`). This pair does not build a URL out of one: the host knows
+   * its CDN base, this library does not, and a guessed URL is a broken image
+   * on every deployment that guessed differently.
+   */
+  readonly icon: string | null;
+  /** The storefront path for this tile. Slug-based, because that is the
+   * route the spec defines — and the reason the client resolves slugs. */
+  readonly href: string;
+}
+
+export interface CategoryCarouselBag {
+  /**
+   * The tiles. `empty` means the catalogue has no `carousel_enabled`
+   * categories — a real configuration, and a landing page that says nothing
+   * rather than showing a spinner forever.
+   */
+  readonly state: LoadState<readonly CarouselEntry[]>;
+  readonly isFetching: boolean;
+  refetch(): void;
+}
+
+export interface CategoryCarouselProps {
+  /** Path prefix for a tile's link. Default `/c` — the spec's `/c/:slug`. */
+  basePath?: string;
+  enabled?: boolean;
+  children: (bag: CategoryCarouselBag) => ReactNode;
+}
+
+/**
+ * The landing page's category strip.
+ *
+ * `GET /categories/carousel/` is the one endpoint that arrives ready to
+ * render: the server filters `active` AND `carousel_enabled`, orders by
+ * `tn_priority` descending, caches the serialization and sends
+ * `Cache-Control: public, max-age`. So this component does no filtering of its
+ * own — it maps rows to tiles and says which strings still need translating.
+ */
+export function CategoryCarousel(props: CategoryCarouselProps): ReactNode {
+  const base = props.basePath ?? "/c";
+  const query = useCategoryCarousel(
+    props.enabled !== undefined ? { enabled: props.enabled } : {}
+  );
+  const state = loadStateFromQuery(query);
+
+  return props.children({
+    state: mapLoad(state, (rows) =>
+      rows.map((category) => ({
+        category,
+        label: categoryLabel(category),
+        icon:
+          category.carousel_icon !== undefined && category.carousel_icon !== ""
+            ? category.carousel_icon
+            : category.catalog_icon !== undefined && category.catalog_icon !== ""
+              ? category.catalog_icon
+              : null,
+        href: `${base}/${category.slug}`,
+      }))
+    ),
+    isFetching: query.isFetching,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/headless/CategoryFeatures.tsx

@@ -0,0 +1,100 @@
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import { featureType } from "@stapel/attributes-react";
+import type { CategoryFeature } from "../api/types.js";
+import { featureLabel, featureOptionsAreKeys } from "../catalog/labels.js";
+import type { CategoryLabel } from "../catalog/labels.js";
+import { useCategoryFeatures } from "../model/queries.js";
+
+/** One feature of a category, with everything a renderer needs decided. */
+export interface CategoryFeatureEntry {
+  readonly feature: CategoryFeature;
+  /** `kind: "key"` → translate. `translate: "none"` makes it a literal. */
+  readonly label: CategoryLabel;
+  /** `config.type`, or `undefined` when the row carries none. An undefined
+   * type is an UNSUPPORTED type as far as any renderer is concerned —
+   * `@stapel/attributes-react` says so loudly rather than skipping the row. */
+  readonly type: string | undefined;
+  readonly mandatory: boolean;
+  /** Are this feature's option labels translation keys? Only under
+   * `translate: "all"` and while `translatable_options` is not false. */
+  readonly optionsAreKeys: boolean;
+}
+
+export interface CategoryFeaturesBag {
+  /**
+   * The feature schema. `empty` means the category declares no features and
+   * inherits none — common for a root category, and a compose form that says
+   * "no extra details for this category" rather than spinning.
+   */
+  readonly state: LoadState<readonly CategoryFeatureEntry[]>;
+  /**
+   * The raw `FeatureDef[]`, ready to hand straight to
+   * `@stapel/attributes-react`'s `<FeatureFields>`, `unsupportedTypeGate`,
+   * `mirrorValidate` or `formatFeatureValue`. Kept beside the decorated list
+   * because those functions take the wire shape, and re-deriving it from
+   * `entries` would be a second mapping to keep in step.
+   */
+  readonly features: readonly CategoryFeature[];
+  /** Only the features marked `show_as_badge` — the card's summary line. */
+  readonly badges: readonly CategoryFeature[];
+  /** Only the features marked `show_at_title` — the generated title parts. */
+  readonly titleParts: readonly CategoryFeature[];
+  readonly isFetching: boolean;
+  refetch(): void;
+}
+
+export interface CategoryFeaturesProps {
+  categoryId: number | null | undefined;
+  enabled?: boolean;
+  children: (bag: CategoryFeaturesBag) => ReactNode;
+}
+
+/**
+ * A category's feature schema — the bridge to `@stapel/attributes-react`.
+ *
+ * `GET /categories/{id}/features/` resolves inheritance and order server-side
+ * and returns `FeatureCompact` rows whose `config` is the polymorphic
+ * attributes config, VERBATIM: `FeatureCompactSerializer.get_config` returns
+ * `obj.config`, not `get_config_with_defaults()`. So an absent config key
+ * means "the type's default", never "off", and this pair does not restate
+ * those defaults — attributes-react owns them (its §13.2 note 1).
+ *
+ * The two consumers this exists for:
+ *
+ *  - the **compose form** (`listings-react`), which draws the features with
+ *    attributes-react's editor registry and blocks submit on a type this
+ *    build cannot draw; and
+ *  - the **facet panel** (`search-react`), whose `categoryFeatures` slot takes
+ *    exactly `features` below and uses it to caption facet values.
+ *
+ * Neither of them re-fetches: a host mounts this once per category page.
+ */
+export function CategoryFeatures(props: CategoryFeaturesProps): ReactNode {
+  const query = useCategoryFeatures(
+    props.categoryId,
+    props.enabled !== undefined ? { enabled: props.enabled } : {}
+  );
+  const state = loadStateFromQuery(query);
+  const features = state.status === "ready" ? state.data : [];
+
+  return props.children({
+    state: mapLoad(state, (rows) =>
+      rows.map((feature) => ({
+        feature,
+        label: featureLabel(feature),
+        type: featureType(feature),
+        mandatory: feature.mandatory === true,
+        optionsAreKeys: featureOptionsAreKeys(feature),
+      }))
+    ),
+    features,
+    badges: features.filter((f) => f.show_as_badge === true),
+    titleParts: features.filter((f) => f.show_at_title === true),
+    isFetching: query.isFetching,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}