@stapel/attributes-react 0.1.0

package/src/default/FeatureBadges.tsx

@@ -0,0 +1,123 @@
+/**
+ * The DISPLAY half — `<FeatureBadges/>` for a card, `<FeatureValueList/>` for
+ * a detail page. Both are renderers over `formatFeatureValue`; neither
+ * re-implements a single type's formatting.
+ *
+ * Two rules they hold that a naive spec table does not:
+ *
+ *  - **An unreadable value says so.** A type this build cannot format renders
+ *    a named notice, not an empty cell — the display twin of the unsupported
+ *    editor. A blank cell where a spec line belongs reads as "this listing
+ *    has no engine size", which is a different and false statement.
+ *  - **`show_as_badge` / `show_at_title` are the CATEGORY's decision**, made
+ *    by whoever configured the feature, and this component honours it instead
+ *    of picking its own first three values.
+ */
+import type { ReactElement } from "react";
+import { Descriptions, Flex, Tag, Typography } from "antd";
+import { useI18n, useT } from "@stapel/core";
+import type { FeatureDef, FeaturesDto } from "../types.js";
+import { featureName, featureType } from "../types.js";
+import { formatFeatureValue, hexColorSwatch } from "../format.js";
+import { ATTRIBUTES_I18N_KEYS } from "../i18n/keys.js";
+
+export interface FeatureDisplayProps {
+  readonly features: readonly FeatureDef[];
+  /** The stored values, in the same `{slug: {type, value}}` envelope the
+   * composer submitted. */
+  readonly values: FeaturesDto;
+}
+
+/** Feature + its formatted value, in the order the category declared. */
+function useRows(
+  props: FeatureDisplayProps,
+  only?: (feature: FeatureDef) => boolean
+): readonly {
+  readonly feature: FeatureDef;
+  readonly text: string | undefined;
+  readonly swatch: string | undefined;
+}[] {
+  const t = useT();
+  const { locale } = useI18n();
+  return props.features
+    .filter((feature) => featureType(feature) !== "header")
+    .filter((feature) => (only ? only(feature) : true))
+    .map((feature) => {
+      const dto = props.values[feature.slug];
+      return {
+        feature,
+        text: formatFeatureValue(feature, dto, { t, locale }),
+        swatch: featureType(feature) === "hex_color" ? hexColorSwatch(dto) : undefined,
+      };
+    });
+}
+
+/** A row's value, or the named reason there is none. */
+function ValueText(props: {
+  readonly feature: FeatureDef;
+  readonly text: string | undefined;
+  readonly hasValue: boolean;
+}): ReactElement {
+  const t = useT();
+  if (props.text !== undefined) return <>{props.text}</>;
+  const type = featureType(props.feature);
+  // Two different absences, said differently: nothing was entered, versus
+  // something was entered that this build cannot read.
+  if (!props.hasValue || type === undefined) {
+    return (
+      <Typography.Text type="secondary">{t(ATTRIBUTES_I18N_KEYS.valueNotSet)}</Typography.Text>
+    );
+  }
+  return (
+    <Typography.Text type="warning" data-testid="attributes-unreadable-value">
+      {t(ATTRIBUTES_I18N_KEYS.valueUnreadable, { type })}
+    </Typography.Text>
+  );
+}
+
+/**
+ * The `show_as_badge` values, as antd `Tag`s — what a result card shows under
+ * a title. Features with no value are omitted here (a card is a summary, and
+ * "not specified" is not a selling point); the detail list below says it
+ * explicitly instead.
+ */
+export function FeatureBadges(props: FeatureDisplayProps): ReactElement {
+  const rows = useRows(props, (feature) => feature.show_as_badge === true);
+  const shown = rows.filter((row) => row.text !== undefined);
+  return (
+    <Flex gap={4} wrap data-testid="attributes-badges">
+      {shown.map((row) => (
+        <Tag
+          key={row.feature.slug}
+          {...(row.swatch ? { color: row.swatch } : {})}
+          data-testid={`attributes-badge-${row.feature.slug}`}
+        >
+          {row.text}
+        </Tag>
+      ))}
+    </Flex>
+  );
+}
+
+/** Every feature and its value — the spec table of a detail page. */
+export function FeatureValueList(props: FeatureDisplayProps): ReactElement {
+  const rows = useRows(props);
+  return (
+    <Descriptions
+      column={1}
+      size="small"
+      data-testid="attributes-value-list"
+      items={rows.map((row) => ({
+        key: row.feature.slug,
+        label: featureName(row.feature),
+        children: (
+          <ValueText
+            feature={row.feature}
+            text={row.text}
+            hasValue={props.values[row.feature.slug] !== undefined}
+          />
+        ),
+      }))}
+    />
+  );
+}

package/src/default/FeatureFields.tsx

@@ -0,0 +1,140 @@
+/**
+ * `<FeatureFields/>` — a category's features, drawn as antd form rows, and
+ * the place the three-rung ladder is actually executed.
+ *
+ * It holds no state and owns no submit: values and errors come in, changes go
+ * out. That is what lets the composer that DOES own the submit
+ * (listings-react) keep one source of truth for a draft, and what lets this
+ * component be dropped into any form — a filter panel, an admin preview —
+ * without dragging a mutation along.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Alert, Form } from "antd";
+import { useFormatFlowError, useT } from "@stapel/core";
+import type { FlowError } from "@stapel/core";
+import type { FeatureDef } from "../types.js";
+import { featureName, featureType } from "../types.js";
+import { resolveValueEditor } from "../registry.js";
+import { BUILTIN_VALUE_EDITORS } from "./editors.js";
+import { ATTRIBUTES_I18N_KEYS } from "../i18n/keys.js";
+
+/** Stable per-feature DOM id, so `<label for>` reaches the control. Slugs are
+ * `[a-z0-9_]`-shaped by the engine, so this needs no further escaping. */
+export function featureControlId(slug: string): string {
+  return `attributes-field-${slug}`;
+}
+
+export interface UnsupportedValueEditorProps {
+  readonly feature: FeatureDef;
+}
+
+/**
+ * The loud last rung. NOT a skipped field: a category can legally carry a
+ * type this build has no editor for, and drawing nothing would silently drop
+ * a feature that may be mandatory — the person would submit a listing they
+ * could not complete and be told, by the server, that an attribute they never
+ * saw is missing.
+ */
+export function UnsupportedValueEditor(
+  props: UnsupportedValueEditorProps
+): ReactElement {
+  const t = useT();
+  const type = featureType(props.feature);
+  return (
+    <Alert
+      type="warning"
+      showIcon
+      data-testid="attributes-unsupported-type"
+      message={featureName(props.feature)}
+      description={
+        type === undefined
+          ? t(ATTRIBUTES_I18N_KEYS.untypedFeature)
+          : t(ATTRIBUTES_I18N_KEYS.unsupportedType, { type })
+      }
+    />
+  );
+}
+
+export interface FeatureFieldsProps {
+  readonly features: readonly FeatureDef[];
+  /** Current answers keyed by slug. The DTO envelope is built at submit time
+   * with `toFeaturesDto`, not held here. */
+  readonly values: Readonly<Record<string, unknown>>;
+  onChange(slug: string, value: unknown): void;
+  /** Refusals keyed by slug — mirrored or from the server, folded through
+   * `featureErrorsBySlug` either way. */
+  readonly errors?: Readonly<Record<string, FlowError>>;
+  /** True while a submit is in flight — every editor goes read-only. */
+  readonly disabled?: boolean;
+  /** Rendered instead of a default `Form.Item` row, for a host with its own
+   * field chrome. */
+  readonly renderRow?: (row: FeatureRowProps) => ReactNode;
+}
+
+export interface FeatureRowProps {
+  readonly feature: FeatureDef;
+  readonly controlId: string;
+  readonly control: ReactNode;
+  readonly error: FlowError | undefined;
+  readonly required: boolean;
+}
+
+function FeatureRow(props: FeatureRowProps): ReactElement {
+  const format = useFormatFlowError();
+  // A header is a caption: no label, no colon, no required marker — rendering
+  // one inside a labelled Form.Item would make a section heading look like a
+  // question.
+  if (featureType(props.feature) === "header") {
+    return <Form.Item style={{ marginBottom: 8 }}>{props.control}</Form.Item>;
+  }
+  return (
+    <Form.Item
+      label={featureName(props.feature)}
+      htmlFor={props.controlId}
+      required={props.required}
+      {...(props.error ? { validateStatus: "error" as const, help: format(props.error) } : {})}
+    >
+      {props.control}
+    </Form.Item>
+  );
+}
+
+/** A category's features as form rows, each drawn by the ladder's winner. */
+export function FeatureFields(props: FeatureFieldsProps): ReactElement {
+  const errors = props.errors ?? {};
+  return (
+    <>
+      {props.features.map((feature) => {
+        const controlId = featureControlId(feature.slug);
+        const type = featureType(feature);
+        // The ladder: a host's explicit registration outranks the skin's
+        // builtin, and nothing at all is a NOTICE, never an omission.
+        const Editor =
+          (type === undefined ? null : resolveValueEditor(type)) ??
+          (type === undefined ? undefined : BUILTIN_VALUE_EDITORS[type]);
+        const control =
+          Editor === undefined || Editor === null ? (
+            <UnsupportedValueEditor feature={feature} />
+          ) : (
+            <Editor
+              id={controlId}
+              feature={feature}
+              value={props.values[feature.slug]}
+              onChange={(value) => props.onChange(feature.slug, value)}
+              error={errors[feature.slug]}
+              disabled={props.disabled === true}
+            />
+          );
+        const row: FeatureRowProps = {
+          feature,
+          controlId,
+          control,
+          error: errors[feature.slug],
+          required: feature.mandatory === true,
+        };
+        if (props.renderRow) return <div key={feature.slug}>{props.renderRow(row)}</div>;
+        return <FeatureRow key={feature.slug} {...row} />;
+      })}
+    </>
+  );
+}