@stapel/reviews-react 0.1.0

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/RatingBadge.tsx

@@ -0,0 +1,81 @@
+/**
+ * `<RatingBadge>` — the stars-and-count line, over either source of the two
+ * numbers.
+ *
+ * The whole component is built around one refusal: when `count` is `0` there
+ * is no star row at all, only the "no reviews yet" sentence. antd's `<Rate>`
+ * given `value={0}` draws five empty stars, which is a perfectly good
+ * rendering of the worst possible score and a completely wrong rendering of
+ * "nobody has rated this". `ratingSummary()` makes the distinction, and this
+ * skin honours it by not reaching `<Rate>` at all in that arm.
+ */
+import type { ReactElement } from "react";
+import { Flex, Rate, Skeleton, Typography } from "antd";
+import { matchLoad, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import { ReviewAggregate } from "../headless/ReviewAggregate.js";
+import type { ReviewAggregateProps } from "../headless/ReviewAggregate.js";
+import { REVIEWS_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { ReviewsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export type RatingBadgeProps = ThemeModeProp &
+  Omit<ReviewAggregateProps, "children">;
+
+export function RatingBadge(props: RatingBadgeProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const { mode, ...aggregateProps } = props;
+
+  return (
+    <ReviewsSkinTheme {...(mode !== undefined ? { mode } : {})}>
+      <ReviewAggregate {...aggregateProps}>
+        {(bag) => (
+          <Flex align="center" gap={8} data-testid="reviews-rating">
+            {matchLoad(bag.state, {
+              loading: () => (
+                <Skeleton.Button active data-testid="reviews-rating-loading" />
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="reviews-rating-failed"
+                  error={describe(toFlowError(error))}
+                />
+              ),
+              ready: (summary) =>
+                summary.rated ? (
+                  <>
+                    <Rate
+                      disabled
+                      allowHalf
+                      count={bag.max}
+                      value={summary.rounded}
+                      data-testid="reviews-rating-stars"
+                    />
+                    <Typography.Text strong>
+                      {t(REVIEWS_I18N_KEYS.ratingValue, {
+                        avg: summary.rounded,
+                        max: bag.max,
+                      })}
+                    </Typography.Text>
+                    <Typography.Text type="secondary">
+                      {t(REVIEWS_I18N_KEYS.ratingCount, {
+                        count: summary.count,
+                      })}
+                    </Typography.Text>
+                  </>
+                ) : (
+                  <Typography.Text
+                    type="secondary"
+                    data-testid="reviews-rating-none"
+                  >
+                    {t(REVIEWS_I18N_KEYS.ratingNone)}
+                  </Typography.Text>
+                ),
+            })}
+          </Flex>
+        )}
+      </ReviewAggregate>
+    </ReviewsSkinTheme>
+  );
+}

package/src/default/ReviewFormCard.tsx

@@ -0,0 +1,139 @@
+/**
+ * `<ReviewFormCard>` — "rate this", in antd.
+ *
+ * Two outcomes get their own sentence rather than a red banner, because
+ * neither is a fault of the person in front of the screen:
+ *
+ * - **already rated** (`error.400.reviews_duplicate_review`, a 400 — see
+ *   `model/refusals.ts`): the form collapses into a note. The same note shows
+ *   when the host told us up front via `alreadyReviewed`, so the two paths to
+ *   the same fact look the same;
+ * - **sent but not visible**: under pre-moderation the created row comes back
+ *   `pending`, and the author is told it will appear once checked. Saying
+ *   "published" there, or saying nothing, leaves them hunting for a review
+ *   that is deliberately invisible to them.
+ */
+import type { ReactElement } from "react";
+import { Alert, Button, Card, Flex, Input, Rate, Typography } from "antd";
+import { useActionGate, useDescribeFlowError, useT } from "@stapel/core";
+import type { ReviewTarget } from "../api/types.js";
+import { ReviewForm } from "../headless/ReviewForm.js";
+import type { ReviewFormBag } from "../headless/ReviewForm.js";
+import { REVIEWS_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { ReviewsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface ReviewFormCardProps extends ThemeModeProp {
+  readonly target: ReviewTarget;
+  /** The host already knows this author has reviewed the target (optimistic). */
+  readonly alreadyReviewed?: boolean;
+}
+
+/** The sentence for a review that exists but may not be on the page. */
+function sentKey(bag: ReviewFormBag): string {
+  switch (bag.submittedVisibility) {
+    case "published":
+      return REVIEWS_I18N_KEYS.formSentPublished;
+    case "pending":
+      return REVIEWS_I18N_KEYS.formSentPending;
+    case "hidden":
+      return REVIEWS_I18N_KEYS.formSentHidden;
+    default:
+      return REVIEWS_I18N_KEYS.formSentUnknown;
+  }
+}
+
+function FormBody(props: { bag: ReviewFormBag }): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const { bag } = props;
+  const gate = useActionGate(bag.canSubmit);
+
+  if (bag.submitted !== null) {
+    return (
+      <Alert
+        type="success"
+        showIcon
+        data-testid="reviews-form-sent"
+        message={t(sentKey(bag))}
+      />
+    );
+  }
+
+  if (bag.alreadyReviewed) {
+    return (
+      <Typography.Text type="secondary" data-testid="reviews-form-duplicate">
+        {t(REVIEWS_I18N_KEYS.submitBlockedDuplicate)}
+      </Typography.Text>
+    );
+  }
+
+  if (bag.signInRequired) {
+    return (
+      <Typography.Text type="secondary" data-testid="reviews-form-sign-in">
+        {t(REVIEWS_I18N_KEYS.formSignInRequired)}
+      </Typography.Text>
+    );
+  }
+
+  return (
+    <Flex vertical gap={8}>
+      <Typography.Text>{t(REVIEWS_I18N_KEYS.formRatingLabel)}</Typography.Text>
+      <Rate
+        count={bag.bounds.max}
+        value={bag.rating ?? 0}
+        onChange={bag.setRating}
+        data-testid="reviews-form-rate"
+      />
+      <Typography.Text>{t(REVIEWS_I18N_KEYS.formBodyLabel)}</Typography.Text>
+      <Input.TextArea
+        value={bag.body}
+        onChange={(event) => bag.setBody(event.target.value)}
+        placeholder={t(REVIEWS_I18N_KEYS.formBodyPlaceholder)}
+        rows={3}
+        data-testid="reviews-form-body"
+      />
+      {bag.error ? (
+        <ErrorAlert testId="reviews-form-failed" error={describe(bag.error)} />
+      ) : null}
+      <Flex vertical gap={4} align="flex-start">
+        <Button
+          type="primary"
+          onClick={bag.submit}
+          disabled={gate.disabled}
+          loading={bag.submitting}
+          data-testid="reviews-form-submit"
+          data-analytics="none"
+          data-analytics-reason="business action — the host app wraps this with its own tracked(); the pair ships no analytics runtime and no flow machine for a single POST"
+        >
+          {t(REVIEWS_I18N_KEYS.formSubmit)}
+        </Button>
+        {gate.reason ? (
+          <Typography.Text type="secondary" data-testid="reviews-form-blocked">
+            {gate.reason}
+          </Typography.Text>
+        ) : null}
+      </Flex>
+    </Flex>
+  );
+}
+
+export function ReviewFormCard(props: ReviewFormCardProps): ReactElement {
+  const t = useT();
+  const { mode, ...formProps } = props;
+  return (
+    <ReviewsSkinTheme {...(mode !== undefined ? { mode } : {})}>
+      <Card size="small" data-testid="reviews-form">
+        <Flex vertical gap={8}>
+          <Typography.Title level={5} style={{ margin: 0 }}>
+            {t(REVIEWS_I18N_KEYS.formHeading)}
+          </Typography.Title>
+          <ReviewForm {...formProps}>
+            {(bag) => <FormBody bag={bag} />}
+          </ReviewForm>
+        </Flex>
+      </Card>
+    </ReviewsSkinTheme>
+  );
+}

package/src/default/ReviewListPanel.tsx

@@ -0,0 +1,204 @@
+/**
+ * `<ReviewListPanel>` — the antd rendering of the review list.
+ *
+ * Two things it says out loud that a naive list would swallow:
+ *
+ * 1. A row that is not `published` carries a badge naming its state. It is on
+ *    screen only because a moderator asked for `include=all`, and a pending
+ *    or hidden review that looked like an ordinary one would misrepresent
+ *    what the public can see.
+ * 2. The author is a SLOT. The wire carries `author_id` and nothing else — no
+ *    name, no avatar — so the skin renders a neutral label unless the host
+ *    passes `renderAuthor`. Printing a raw user id would be both useless to a
+ *    reader and a gratuitous disclosure.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Button, Card, Empty, Flex, List, Rate, Skeleton, Tag, Typography } from "antd";
+import {
+  matchLoad,
+  toFlowError,
+  useActionGate,
+  useDescribeFlowError,
+  useT,
+} from "@stapel/core";
+import type { Review, ReviewTarget } from "../api/types.js";
+import { ReviewList } from "../headless/ReviewList.js";
+import type { ReviewListBag } from "../headless/ReviewList.js";
+import { REVIEWS_I18N_KEYS } from "../i18n/keys.js";
+import { reviewVisibility } from "../model/list.js";
+import { useReviewsRuntime } from "../model/context.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { ReviewsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface ReviewListPanelProps extends ThemeModeProp {
+  readonly target: ReviewTarget;
+  /** Ask for pending/hidden rows (granted only to a moderator of the target). */
+  readonly include?: "all";
+  readonly limit?: number;
+  /** Turn `author_id` into something a reader recognises. See the header. */
+  readonly renderAuthor?: (review: Review) => ReactNode;
+  /** Format `created_at`. Absent means the raw ISO string is NOT shown. */
+  readonly renderDate?: (review: Review) => ReactNode;
+}
+
+/** The badge a non-published row carries. `null` for an ordinary review. */
+function VisibilityTag(props: { status: string }): ReactElement | null {
+  const t = useT();
+  const visibility = reviewVisibility(props.status);
+  if (visibility === "published") return null;
+  if (visibility === "pending") {
+    return (
+      <Tag color="warning" data-testid="reviews-row-pending">
+        {t(REVIEWS_I18N_KEYS.statusPending)}
+      </Tag>
+    );
+  }
+  if (visibility === "hidden") {
+    return (
+      <Tag color="error" data-testid="reviews-row-hidden">
+        {t(REVIEWS_I18N_KEYS.statusHidden)}
+      </Tag>
+    );
+  }
+  // A state this build does not know. Naming it beats rendering it as an
+  // ordinary review (it may be one the server hides) and beats crashing.
+  return (
+    <Tag data-testid="reviews-row-unknown">
+      {t(REVIEWS_I18N_KEYS.statusUnknown, { status: props.status })}
+    </Tag>
+  );
+}
+
+function ReviewRow(props: {
+  review: Review;
+  max: number;
+  renderAuthor: ReviewListPanelProps["renderAuthor"];
+  renderDate: ReviewListPanelProps["renderDate"];
+}): ReactElement {
+  const t = useT();
+  const { review } = props;
+  return (
+    <List.Item data-testid="reviews-row" data-review-id={review.id}>
+      <Flex vertical gap={4} style={{ width: "100%" }}>
+        <Flex align="center" gap={8} wrap>
+          <Rate disabled count={props.max} value={review.rating} />
+          <Typography.Text strong>
+            {props.renderAuthor?.(review) ?? t(REVIEWS_I18N_KEYS.authorFallback)}
+          </Typography.Text>
+          {props.renderDate ? (
+            <Typography.Text type="secondary">
+              {props.renderDate(review)}
+            </Typography.Text>
+          ) : null}
+          <VisibilityTag status={review.status} />
+        </Flex>
+        {review.body.length > 0 ? (
+          <Typography.Paragraph style={{ margin: 0 }}>
+            {review.body}
+          </Typography.Paragraph>
+        ) : null}
+        {review.response ? (
+          <Card size="small" data-testid="reviews-row-response">
+            <Typography.Text type="secondary">
+              {t(REVIEWS_I18N_KEYS.responseHeading)}
+            </Typography.Text>
+            <Typography.Paragraph style={{ margin: 0 }}>
+              {review.response.body}
+            </Typography.Paragraph>
+          </Card>
+        ) : null}
+      </Flex>
+    </List.Item>
+  );
+}
+
+function MoreButton(props: { bag: ReviewListBag }): ReactElement {
+  const t = useT();
+  const gate = useActionGate(props.bag.more);
+  return (
+    <Flex vertical align="center" gap={4}>
+      <Button
+        onClick={props.bag.loadMore}
+        disabled={gate.disabled}
+        loading={props.bag.loadingMore}
+        data-testid="reviews-load-more"
+        data-analytics="none"
+        data-analytics-reason="paging further into a read — the host app wraps this with its own tracked(); pairs carry no @stapel/analytics runtime dependency by architecture"
+      >
+        {t(REVIEWS_I18N_KEYS.listLoadMore)}
+      </Button>
+      {gate.reason ? (
+        <Typography.Text type="secondary" data-testid="reviews-load-more-reason">
+          {gate.reason}
+        </Typography.Text>
+      ) : null}
+    </Flex>
+  );
+}
+
+export function ReviewListPanel(props: ReviewListPanelProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const runtime = useReviewsRuntime();
+  const { mode, target, renderAuthor, renderDate, ...listOptions } = props;
+
+  return (
+    <ReviewsSkinTheme {...(mode !== undefined ? { mode } : {})}>
+      <ReviewList target={target} {...listOptions}>
+        {(bag) => (
+          <Flex vertical gap={8} data-testid="reviews-list">
+            <Typography.Title level={5} style={{ margin: 0 }}>
+              {t(REVIEWS_I18N_KEYS.listHeading)}
+            </Typography.Title>
+
+            {matchLoad(bag.state, {
+              loading: () => (
+                <Skeleton active data-testid="reviews-list-loading" />
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="reviews-list-failed"
+                  error={describe(toFlowError(error))}
+                  action={
+                    <Button
+                      size="small"
+                      onClick={bag.refresh}
+                      data-analytics="none"
+                      data-analytics-reason="recovery affordance for a failed read — host app wraps with its own tracked()"
+                    >
+                      {t(REVIEWS_I18N_KEYS.listRefresh)}
+                    </Button>
+                  }
+                />
+              ),
+              ready: (reviews) =>
+                reviews.length === 0 ? (
+                  <Empty
+                    data-testid="reviews-list-empty"
+                    description={t(REVIEWS_I18N_KEYS.listEmpty)}
+                  />
+                ) : (
+                  <>
+                    <List
+                      dataSource={[...reviews]}
+                      data-testid="reviews-list-rows"
+                      renderItem={(review: Review) => (
+                        <ReviewRow
+                          review={review}
+                          max={runtime.ratingBounds.max}
+                          renderAuthor={renderAuthor}
+                          renderDate={renderDate}
+                        />
+                      )}
+                    />
+                    <MoreButton bag={bag} />
+                  </>
+                ),
+            })}
+          </Flex>
+        )}
+      </ReviewList>
+    </ReviewsSkinTheme>
+  );
+}

package/src/default/ReviewsPanel.tsx

@@ -0,0 +1,74 @@
+/**
+ * `<ReviewsPanel>` — the composed block a listing detail page drops in: the
+ * rating line, the list, and (for a signed-in reader who has not rated yet)
+ * the form.
+ *
+ * The pre-check is the interesting part, and its LIMIT is the reason it lives
+ * here rather than inside the form. Given `viewerId`, the panel looks for the
+ * viewer's own review among the loaded rows and, finding one, tells the form
+ * not to offer itself. That list is published-only, so under pre-moderation
+ * the viewer's pending review is invisible even to them: the form is offered,
+ * the server refuses with `error.400.reviews_duplicate_review`, and the form
+ * shows the same "you have already rated this" sentence. One fact, two
+ * discoveries, one sentence — which is why the refusal is a first-class
+ * outcome and the pre-check is only an optimisation.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Flex } from "antd";
+import type { Review, ReviewTarget } from "../api/types.js";
+import { ReviewList } from "../headless/ReviewList.js";
+import { findOwnReview } from "../model/list.js";
+import { RatingBadge } from "./RatingBadge.js";
+import { ReviewFormCard } from "./ReviewFormCard.js";
+import { ReviewListPanel } from "./ReviewListPanel.js";
+import { ReviewsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface ReviewsPanelProps extends ThemeModeProp {
+  readonly target: ReviewTarget;
+  /**
+   * The reader's user id — the value the backend puts in `author_id`, NOT a
+   * profile id. Absent means no pre-check: the form is offered and the server
+   * is the only judge.
+   */
+  readonly viewerId?: string | null;
+  /** Hide the form entirely (a seller looking at their own listing). */
+  readonly canReview?: boolean;
+  readonly renderAuthor?: (review: Review) => ReactNode;
+  readonly renderDate?: (review: Review) => ReactNode;
+}
+
+export function ReviewsPanel(props: ReviewsPanelProps): ReactElement {
+  const { mode, target, viewerId, canReview = true, ...rows } = props;
+  return (
+    <ReviewsSkinTheme {...(mode !== undefined ? { mode } : {})}>
+      <Flex vertical gap={16} data-testid="reviews-panel">
+        <RatingBadge target={target} {...(mode !== undefined ? { mode } : {})} />
+        <ReviewListPanel
+          target={target}
+          {...(mode !== undefined ? { mode } : {})}
+          {...rows}
+        />
+        {canReview ? (
+          // The list is read a second time here, from the SAME query key, so
+          // this is a cache hit rather than a second request — the own-review
+          // pre-check needs the rows and the panel needs them rendered.
+          <ReviewList target={target}>
+            {(bag) => (
+              <ReviewFormCard
+                target={target}
+                {...(mode !== undefined ? { mode } : {})}
+                alreadyReviewed={
+                  findOwnReview(
+                    bag.state.status === "ready" ? bag.state.data : undefined,
+                    viewerId
+                  ) !== undefined
+                }
+              />
+            )}
+          </ReviewList>
+        ) : null}
+      </Flex>
+    </ReviewsSkinTheme>
+  );
+}

package/src/default/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `@stapel/reviews-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 review block 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 { createReviewsRuntime, ReviewsProvider } from "@stapel/reviews-react";
+ * import { ReviewsPanel } from "@stapel/reviews-react/default";
+ * ```
+ *
+ * `<RatingBadge aggregate={…}>` is the seller-rating half: it renders two
+ * numbers the composite's projection produced, because stapel-reviews cannot
+ * roll a seller's listings up itself (main entry header).
+ */
+export { ReviewsPanel } from "./ReviewsPanel.js";
+export type { ReviewsPanelProps } from "./ReviewsPanel.js";
+export { ReviewListPanel } from "./ReviewListPanel.js";
+export type { ReviewListPanelProps } from "./ReviewListPanel.js";
+export { ReviewFormCard } from "./ReviewFormCard.js";
+export type { ReviewFormCardProps } from "./ReviewFormCard.js";
+export { RatingBadge } from "./RatingBadge.js";
+export type { RatingBadgeProps } from "./RatingBadge.js";
+export { ReviewsSkinTheme } from "./theme.js";
+export type { ReviewsSkinThemeProps } from "./theme.js";
+export { ErrorAlert } from "./ErrorAlert.js";
+export type { ThemeModeProp } from "./types.js";

package/src/default/theme.tsx

@@ -0,0 +1,66 @@
+/**
+ * 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 ReviewsSkinThemeProps {
+  /**
+   * 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;
+}
+
+/**
+ * `<ReviewsSkinTheme/>` — the self-theming wrapper of
+ * `@stapel/reviews-react/default`. Standalone use is supported (wrap any
+ * composition of the skin's parts once); the shipped surfaces
+ * (`ReviewsPanel`, `ReviewListPanel`, `ReviewFormCard`, `RatingBadge`)
+ * each already wrap themselves, and nested antd
+ * `ConfigProvider`s merge, so composing them under one `ReviewsSkinTheme`
+ * stays correct.
+ */
+export function ReviewsSkinTheme(props: ReviewsSkinThemeProps): ReactElement {
+  const mode = props.mode ?? resolveThemeMode();
+  const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
+  const token = useMemo(() => toAntdTheme(mode), [mode]);
+  return (
+    <ConfigProvider theme={theme}>
+      <div
+        data-reviews-skin-root
+        data-reviews-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;
+}