feedback

Submit bounded document feedback

Install

docsloth component add @docsloth/feedback@1.0.0

Live package: sha256:ea984d36a3eb7427a33d3fc3c31ca3ee5389ca9973a7b21c42ef5bb740ead3c5 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/feedback.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "page_id": "00000000-0000-4000-8000-000000000000",
  "publication_id": "00000000-0000-4000-8000-000000000000",
  "prompt": "example-prompt",
  "allow_comment": true
}

Required props: page_id, publication_id, prompt, allow_comment.

Example

Example document IR (the block the renderer consumes):

{
  "type": "feedback",
  "props": {
    "title": "example-title",
    "page_id": "00000000-0000-4000-8000-000000000000",
    "publication_id": "00000000-0000-4000-8000-000000000000",
    "prompt": "example-prompt",
    "allow_comment": true
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-feedback" data-component="feedback" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<p>example-prompt</p>
<dl class="ds-facts">
<div>
<dt>Comments</dt>
<dd>Welcome</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Sending feedback needs the live documentation site.</p>
</section>

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/feedback.md.

Contract

Production props are normative in ../contracts/component-props/feedback.schema.json. The corresponding component-fixtures manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated component-package.json manifest plus props.schema.json (the production props schema, copied byte-for-byte) and spec.md (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

Intended behavior

Useful yes/no and bounded feedback with disclosure of processing, not identity requirement by default.

Failure and fallback

Retry preserves idempotency; abusive input safely stored/redacted.

The React implementation resolves ComponentContentProvider.feedback through feedbackKey(publication_id, page_id). Available records supply a matching release, publication, page, form version, actor session, processing disclosure and typed submit adapter. Anonymous sessions are allowed. The host authorizes each call, enforces page/publication membership and input/rate limits, redacts or moderates text before storage, and durably deduplicates the scoped idempotency key. These server protections are not supplied by client rendering.

The form retains an unchanged payload's random idempotency key across retries within its mounted scope. Changing the submitted payload creates a new key; scope changes and explicit new-feedback actions reset the draft. A reload does not preserve browser-local drafts or retry keys. Acceptance requires a typed receipt matching the complete scope and key, never a generic HTTP success or executor stdout. Cancellation stops waiting and ignores late replies without claiming that remote storage was rolled back. The optional comment is limited to 2,000 UTF-16 code units. The host must enforce the same or tighter bound.

Without JavaScript the prompt and disclosure remain readable and controls are disabled. Missing, restricted and loading adapters are explicit. No model, executor, browser persistence or billing dispatch is performed by this form. Actual production transport and backend integration remain host responsibilities.

Required acceptance cases

No feedback event converted directly to billable financial event. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/feedback.json.

Sources