@stapel/categories-react 0.1.0

package/src/default/CatalogPage.tsx

@@ -0,0 +1,40 @@
+/**
+ * `<CatalogPage>` — the catalogue root at `/c`: the carousel over the top-level
+ * tree.
+ *
+ * This is a single-pair screen, which is exactly why it has a nav entry while
+ * `/` does not. The storefront's landing composes THIS pair's carousel with
+ * search's newest-listings feed (spec §5.1), and a composed route belongs to
+ * the container that composes it — see `nav/manifest.ts`.
+ */
+import type { ReactElement } from "react";
+import { Flex, Typography } from "antd";
+import { useT } from "@stapel/core";
+import { CATEGORIES_I18N_KEYS } from "../i18n/keys.js";
+import { CategoryCarouselStrip } from "./CategoryCarouselStrip.js";
+import { CategoryTreePane } from "./CategoryTreePane.js";
+import { CategoriesSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface CatalogPageProps extends ThemeModeProp {
+  readonly basePath?: string;
+}
+
+export function CatalogPage(props: CatalogPageProps): ReactElement {
+  const t = useT();
+  const base = props.basePath ?? "/c";
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <Flex vertical gap={16} data-testid="categories-catalog-page">
+        <Typography.Title level={3} style={{ margin: 0 }}>
+          {t(CATEGORIES_I18N_KEYS.catalogTitle)}
+        </Typography.Title>
+        <CategoryCarouselStrip basePath={base} />
+        <CategoryTreePane basePath={base} />
+      </Flex>
+    </CategoriesSkinTheme>
+  );
+}

package/src/default/CategoryBreadcrumbsBar.tsx

@@ -0,0 +1,93 @@
+/**
+ * `<CategoryBreadcrumbsBar>` — root → current, as antd breadcrumbs.
+ *
+ * Every caption goes through `renderCategoryLabel`, which is the one place
+ * this skin decides between "translate this" and "print this": a category's
+ * `name` is a translation KEY unless the row says `translatable: false`
+ * (`catalog/labels.ts`). A skin that called `t()` unconditionally would print
+ * the stored string for an untranslatable category twice-wrapped, and one that
+ * never called it would show `category.electronics` at a visitor.
+ */
+import type { ReactElement } from "react";
+import { Breadcrumb, Skeleton, Typography } from "antd";
+import { matchLoad, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import { renderCategoryLabel } from "../catalog/labels.js";
+import { CategoryBreadcrumbs } from "../headless/CategoryBreadcrumbs.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 CategoryBreadcrumbsBarProps extends ThemeModeProp {
+  readonly slug?: string;
+  readonly categoryId?: number | null;
+  /** Path prefix for a crumb's link. Default `/c`. */
+  readonly basePath?: string;
+}
+
+export function CategoryBreadcrumbsBar(
+  props: CategoryBreadcrumbsBarProps
+): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const base = props.basePath ?? "/c";
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <CategoryBreadcrumbs
+        {...(props.slug !== undefined ? { slug: props.slug } : {})}
+        {...(props.categoryId !== undefined
+          ? { categoryId: props.categoryId }
+          : {})}
+      >
+        {(bag) =>
+          matchLoad(bag.state, {
+            loading: () => (
+              <Skeleton.Input
+                active
+                size="small"
+                data-testid="categories-breadcrumbs-loading"
+              />
+            ),
+            failed: (error) => (
+              <ErrorAlert
+                testId="categories-breadcrumbs-failed"
+                error={{
+                  ...describe(toFlowError(error)),
+                  message: t(CATEGORIES_I18N_KEYS.catalogLoadFailed),
+                }}
+              />
+            ),
+            ready: (crumbs) =>
+              bag.unknownSlug ? (
+                <Typography.Text
+                  type="secondary"
+                  data-testid="categories-breadcrumbs-unknown"
+                >
+                  {t(CATEGORIES_I18N_KEYS.categoryUnknownSlug)}
+                </Typography.Text>
+              ) : (
+                <Breadcrumb
+                  data-testid="categories-breadcrumbs"
+                  items={[
+                    {
+                      title: t(CATEGORIES_I18N_KEYS.breadcrumbsRoot),
+                      href: base,
+                    },
+                    ...crumbs.map((crumb) => ({
+                      title: renderCategoryLabel(crumb.label, t),
+                      ...(crumb.isCurrent
+                        ? {}
+                        : { href: `${base}/${crumb.node.category.slug}` }),
+                    })),
+                  ]}
+                />
+              ),
+          })
+        }
+      </CategoryBreadcrumbs>
+    </CategoriesSkinTheme>
+  );
+}

package/src/default/CategoryCarouselStrip.tsx

@@ -0,0 +1,102 @@
+/**
+ * `<CategoryCarouselStrip>` — the landing page's row of category tiles.
+ *
+ * The icon references (`carousel_icon` / `catalog_icon`) are OPAQUE STRINGS
+ * that the backend deliberately does not resolve ("Decoupled from stapel-cdn:
+ * an opaque string, resolved by the host if at all"). This skin therefore
+ * renders no `<img>` and builds no URL: it hands the reference to the host
+ * through `renderIcon`, and draws nothing when the host does not supply one. A
+ * guessed CDN path would be a broken image on every deployment that guessed
+ * differently, and a broken image is worse than no image.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Card, Empty, Flex, Skeleton, Typography } from "antd";
+import { matchList, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import { renderCategoryLabel } from "../catalog/labels.js";
+import { CategoryCarousel } from "../headless/CategoryCarousel.js";
+import type { CarouselEntry } from "../headless/CategoryCarousel.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 CategoryCarouselStripProps extends ThemeModeProp {
+  readonly basePath?: string;
+  /** Turn an opaque icon reference into something renderable. Absent means no
+   * icon is drawn — see this file's header. */
+  readonly renderIcon?: (reference: string, entry: CarouselEntry) => ReactNode;
+}
+
+export function CategoryCarouselStrip(
+  props: CategoryCarouselStripProps
+): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <CategoryCarousel
+        {...(props.basePath !== undefined ? { basePath: props.basePath } : {})}
+      >
+        {(bag) => (
+          <Flex vertical gap={8} data-testid="categories-carousel">
+            <Typography.Title level={5} style={{ margin: 0 }}>
+              {t(CATEGORIES_I18N_KEYS.carouselTitle)}
+            </Typography.Title>
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex gap={8}>
+                  <Skeleton.Button
+                    active
+                    data-testid="categories-carousel-loading"
+                  />
+                  <Skeleton.Button active />
+                  <Skeleton.Button active />
+                </Flex>
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="categories-carousel-failed"
+                  error={{
+                    ...describe(toFlowError(error)),
+                    message: t(CATEGORIES_I18N_KEYS.carouselLoadFailed),
+                  }}
+                />
+              ),
+              empty: () => (
+                <Empty
+                  data-testid="categories-carousel-empty"
+                  description={t(CATEGORIES_I18N_KEYS.carouselEmpty)}
+                />
+              ),
+              ready: (entries) => (
+                <Flex gap={8} wrap data-testid="categories-carousel-list">
+                  {entries.map((entry) => (
+                    <Card
+                      key={entry.category.id}
+                      size="small"
+                      hoverable
+                      data-category-slug={entry.category.slug}
+                    >
+                      <Typography.Link href={entry.href}>
+                        <Flex align="center" gap={8}>
+                          {entry.icon !== null && props.renderIcon !== undefined
+                            ? props.renderIcon(entry.icon, entry)
+                            : null}
+                          <span>{renderCategoryLabel(entry.label, t)}</span>
+                        </Flex>
+                      </Typography.Link>
+                    </Card>
+                  ))}
+                </Flex>
+              ),
+            })}
+          </Flex>
+        )}
+      </CategoryCarousel>
+    </CategoriesSkinTheme>
+  );
+}

package/src/default/CategoryFeatureList.tsx

@@ -0,0 +1,125 @@
+/**
+ * `<CategoryFeatureList>` — a category's feature SCHEMA, rendered.
+ *
+ * The display integration with `@stapel/attributes-react` in the direction
+ * this pair owns: categories serves the definitions, attributes knows what a
+ * definition MEANS. So the type badge is not a string this file invents —
+ * `featureType` is attributes-react's single reader of `config.type`, and
+ * `BUILTIN_VALUE_EDITOR_TYPES` is its own statement of which types a build can
+ * actually draw. A type outside that set is marked here, on the schema, rather
+ * than discovered when somebody opens the compose form and finds a missing
+ * field.
+ *
+ * The other direction — values, not definitions — belongs to attributes-react
+ * outright: `formatFeatureValue`, `<FeatureBadges>`, `<FeatureValueList>`. A
+ * listing card imports those directly and this pair is not in the path.
+ */
+import type { ReactElement } from "react";
+import { Empty, Flex, List, Spin, Tag, Typography } from "antd";
+import { matchList, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import { BUILTIN_VALUE_EDITOR_TYPES } from "@stapel/attributes-react/default";
+import { renderCategoryLabel } from "../catalog/labels.js";
+import { CategoryFeatures } from "../headless/CategoryFeatures.js";
+import type { CategoryFeatureEntry } from "../headless/CategoryFeatures.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 CategoryFeatureListProps extends ThemeModeProp {
+  readonly categoryId: number | null | undefined;
+}
+
+export function CategoryFeatureList(
+  props: CategoryFeatureListProps
+): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const drawable = new Set<string>(BUILTIN_VALUE_EDITOR_TYPES);
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <CategoryFeatures categoryId={props.categoryId}>
+        {(bag) => (
+          <Flex vertical gap={8} data-testid="categories-features">
+            <Typography.Title level={5} style={{ margin: 0 }}>
+              {t(CATEGORIES_I18N_KEYS.featuresTitle)}
+            </Typography.Title>
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex justify="center" style={{ padding: 16 }}>
+                  <Spin data-testid="categories-features-loading" />
+                </Flex>
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="categories-features-failed"
+                  error={{
+                    ...describe(toFlowError(error)),
+                    message: t(CATEGORIES_I18N_KEYS.featuresLoadFailed),
+                  }}
+                />
+              ),
+              empty: () => (
+                <Empty
+                  data-testid="categories-features-empty"
+                  description={t(CATEGORIES_I18N_KEYS.featuresEmpty)}
+                />
+              ),
+              ready: (entries) => (
+                <List<CategoryFeatureEntry>
+                  data-testid="categories-features-list"
+                  size="small"
+                  dataSource={[...entries]}
+                  renderItem={(entry) => (
+                    <List.Item
+                      key={entry.feature.slug}
+                      data-feature-slug={entry.feature.slug}
+                    >
+                      <Flex
+                        justify="space-between"
+                        align="center"
+                        gap={8}
+                        style={{ width: "100%" }}
+                      >
+                        <Typography.Text>
+                          {renderCategoryLabel(entry.label, t)}
+                        </Typography.Text>
+                        <Flex gap={4} align="center">
+                          {entry.mandatory ? (
+                            <Tag color="red">
+                              {t(CATEGORIES_I18N_KEYS.featuresMandatory)}
+                            </Tag>
+                          ) : null}
+                          {entry.type === undefined ? (
+                            <Tag color="warning" data-feature-untyped>
+                              {t(CATEGORIES_I18N_KEYS.featuresUntyped)}
+                            </Tag>
+                          ) : (
+                            <Tag
+                              {...(drawable.has(entry.type)
+                                ? {}
+                                : { color: "warning" })}
+                              data-feature-type={entry.type}
+                            >
+                              {t(CATEGORIES_I18N_KEYS.featuresType, {
+                                type: entry.type,
+                              })}
+                            </Tag>
+                          )}
+                        </Flex>
+                      </Flex>
+                    </List.Item>
+                  )}
+                />
+              ),
+            })}
+          </Flex>
+        )}
+      </CategoryFeatures>
+    </CategoriesSkinTheme>
+  );
+}

package/src/default/CategoryPage.tsx

@@ -0,0 +1,114 @@
+/**
+ * `<CategoryPage>` — the `/c/:slug` screen: breadcrumbs, sub-categories, and a
+ * SLOT where the listings go.
+ *
+ * The slot is the whole design. Spec §5.1 makes this route "categories +
+ * search": the sub-category menu comes from here, the results with facets come
+ * from `@stapel/search-react`. A pair may not import another L2 pair
+ * (dependency direction is strictly downward), and a screen that rendered only
+ * half of itself would be useless — so the half this pair does not own is a
+ * render prop, handed the resolved category. The container writes one line:
+ *
+ * ```tsx
+ * <CategoryPage
+ *   slug={slug}
+ *   renderListings={(category) => (
+ *     <SearchPage adapter={useRouterSearchParams()} defaultType="listing"
+ *                 fixedCategory={category.id} />
+ *   )}
+ * />
+ * ```
+ *
+ * `slug` resolution happens against the synced tree because the SERVER cannot
+ * do it (`nav/manifest.ts`, `catalog/tree.ts`). Until the catalogue has
+ * loaded, an unknown slug is not yet unknown — the "no category here" line is
+ * shown only once the sync succeeded, so a slow network never renders a 404
+ * for a page that exists.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Empty, Flex, Spin, Typography } from "antd";
+import { toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import type { Category } from "../api/types.js";
+import { categoryLabel, renderCategoryLabel } from "../catalog/labels.js";
+import { CategoryTree } from "../headless/CategoryTree.js";
+import { CATEGORIES_I18N_KEYS } from "../i18n/keys.js";
+import { CategoryBreadcrumbsBar } from "./CategoryBreadcrumbsBar.js";
+import { CategoryFeatureList } from "./CategoryFeatureList.js";
+import { CategoryTreePane } from "./CategoryTreePane.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { CategoriesSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface CategoryPageProps extends ThemeModeProp {
+  /** The `:slug` segment of `/c/:slug`. */
+  readonly slug: string;
+  readonly basePath?: string;
+  /** The listings half of the screen — supplied by the container, because it
+   * belongs to another pair. */
+  readonly renderListings?: (category: Category) => ReactNode;
+  /** Show the category's feature schema. Off by default: on a storefront the
+   * schema is the facet panel's input, not a visitor-facing table. */
+  readonly showFeatures?: boolean;
+}
+
+export function CategoryPage(props: CategoryPageProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const base = props.basePath ?? "/c";
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <CategoryTree slug={props.slug}>
+        {(bag) => (
+          <Flex vertical gap={16} data-testid="categories-category-page">
+            <CategoryBreadcrumbsBar slug={props.slug} basePath={base} />
+
+            {bag.catalog.status === "loading" ? (
+              <Flex justify="center" style={{ padding: 16 }}>
+                <Spin data-testid="categories-category-loading" />
+              </Flex>
+            ) : bag.catalog.status === "failed" ? (
+              <ErrorAlert
+                testId="categories-category-failed"
+                error={{
+                  ...describe(toFlowError(bag.catalog.error)),
+                  message: t(CATEGORIES_I18N_KEYS.catalogLoadFailed),
+                }}
+              />
+            ) : bag.current === null ? (
+              <Empty
+                data-testid="categories-category-unknown"
+                description={t(CATEGORIES_I18N_KEYS.categoryUnknownSlug)}
+              />
+            ) : (
+              <>
+                <Typography.Title level={3} style={{ margin: 0 }}>
+                  {renderCategoryLabel(
+                    categoryLabel(bag.current.category),
+                    t
+                  )}
+                </Typography.Title>
+
+                {bag.current.children.length > 0 ? (
+                  <CategoryTreePane
+                    slug={props.slug}
+                    basePath={base}
+                    titleKey={CATEGORIES_I18N_KEYS.categorySubcategories}
+                  />
+                ) : null}
+
+                {props.showFeatures === true ? (
+                  <CategoryFeatureList categoryId={bag.current.id} />
+                ) : null}
+
+                {props.renderListings?.(bag.current.category)}
+              </>
+            )}
+          </Flex>
+        )}
+      </CategoryTree>
+    </CategoriesSkinTheme>
+  );
+}

package/src/default/CategoryPickerField.tsx

@@ -0,0 +1,173 @@
+/**
+ * `<CategoryPickerField>` — the compose form's category chooser.
+ *
+ * Drill down or search; either way the options come out of the tree that is
+ * already in memory, so typing does not issue a request per keystroke and the
+ * whole control works offline once the catalogue has synced.
+ *
+ * The blocked state carries its reason, always. `ActionAvailability`'s rule is
+ * that a disabled control must say why, and this control has two different
+ * whys — nothing chosen yet, versus a chosen category that still has
+ * sub-categories. The second one matters more than it looks: filing a listing
+ * under "Electronics" instead of "Electronics › Phones" inherits a different
+ * feature set, so the form then asks the wrong questions and the server
+ * refuses a field the person never saw.
+ */
+import type { ReactElement } from "react";
+import { Alert, Breadcrumb, Button, Empty, Flex, Input, List, Spin } 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 { CategoryPicker } from "../headless/CategoryPicker.js";
+import type { CategoryOption } from "../headless/CategoryPicker.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";
+
+const BLOCKED_KEY = {
+  nothing_selected: CATEGORIES_I18N_KEYS.pickerBlockedNothingSelected,
+  not_a_leaf: CATEGORIES_I18N_KEYS.pickerBlockedNotALeaf,
+} as const;
+
+export interface CategoryPickerFieldProps extends ThemeModeProp {
+  readonly value?: number | null;
+  readonly onChange?: (id: number | null, node: CategoryNode | null) => void;
+  /** Only leaf categories are valid. Default `true`. */
+  readonly leavesOnly?: boolean;
+}
+
+export function CategoryPickerField(
+  props: CategoryPickerFieldProps
+): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+
+  return (
+    <CategoriesSkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <CategoryPicker
+        {...(props.value !== undefined ? { value: props.value } : {})}
+        {...(props.onChange !== undefined ? { onChange: props.onChange } : {})}
+        {...(props.leavesOnly !== undefined
+          ? { leavesOnly: props.leavesOnly }
+          : {})}
+        translate={t}
+      >
+        {(bag) => (
+          <Flex vertical gap={8} data-testid="categories-picker">
+            <Input
+              allowClear
+              value={bag.query}
+              placeholder={t(CATEGORIES_I18N_KEYS.pickerSearch)}
+              aria-label={t(CATEGORIES_I18N_KEYS.pickerSearch)}
+              data-testid="categories-picker-search"
+              onChange={(event) => {
+                bag.setQuery(event.target.value);
+              }}
+            />
+
+            {bag.query === "" && bag.path.length > 0 ? (
+              <Flex align="center" gap={8}>
+                <Button
+                  size="small"
+                  data-testid="categories-picker-up"
+                  data-analytics="none"
+                  data-analytics-reason="walking the local tree is a read; nothing leaves the browser"
+                  onClick={bag.up}
+                >
+                  {t(CATEGORIES_I18N_KEYS.pickerUp)}
+                </Button>
+                <Breadcrumb
+                  items={bag.path.map((node) => ({
+                    title: renderCategoryLabel(
+                      categoryLabel(node.category),
+                      t
+                    ),
+                  }))}
+                />
+              </Flex>
+            ) : null}
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex justify="center" style={{ padding: 16 }}>
+                  <Spin data-testid="categories-picker-loading" />
+                </Flex>
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="categories-picker-failed"
+                  error={{
+                    ...describe(toFlowError(error)),
+                    message: t(CATEGORIES_I18N_KEYS.pickerLoadFailed),
+                  }}
+                />
+              ),
+              empty: () => (
+                <Empty
+                  data-testid="categories-picker-empty"
+                  description={t(
+                    bag.query === ""
+                      ? CATEGORIES_I18N_KEYS.categoryNoSubcategories
+                      : CATEGORIES_I18N_KEYS.pickerNoMatches
+                  )}
+                />
+              ),
+              ready: (options) => (
+                <List<CategoryOption>
+                  data-testid="categories-picker-list"
+                  size="small"
+                  dataSource={[...options]}
+                  renderItem={(option) => (
+                    <List.Item
+                      key={option.node.id}
+                      data-category-id={option.node.id}
+                    >
+                      <Button
+                        type="link"
+                        data-testid={`categories-picker-option-${String(option.node.id)}`}
+                        data-analytics="none"
+                        data-analytics-reason="drilling into the local tree is a read; the host tracks the SUBMIT that consumes the chosen category"
+                        onClick={() => {
+                          bag.open(option.node);
+                        }}
+                      >
+                        {renderCategoryLabel(option.label, t)}
+                      </Button>
+                    </List.Item>
+                  )}
+                />
+              ),
+            })}
+
+            {bag.submitBlockedReason !== null ? (
+              <Alert
+                type="info"
+                showIcon
+                data-testid="categories-picker-blocked"
+                message={t(BLOCKED_KEY[bag.submitBlockedReason])}
+              />
+            ) : (
+              <Alert
+                type="success"
+                showIcon
+                data-testid="categories-picker-selected"
+                message={t(CATEGORIES_I18N_KEYS.pickerSelected, {
+                  category:
+                    bag.selected === null
+                      ? ""
+                      : renderCategoryLabel(
+                          categoryLabel(bag.selected.category),
+                          t
+                        ),
+                })}
+              />
+            )}
+          </Flex>
+        )}
+      </CategoryPicker>
+    </CategoriesSkinTheme>
+  );
+}