@firu-daniel/agent-qa-attrs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firu Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# `@firu-daniel/agent-qa-attrs`
+
+A `data-qa-*` attribute contract that makes a React application deterministically drivable — by an
+end-to-end test, and by a browser-driving agent that has to find an element without being told where
+it is on screen.
+
+```bash
+npm i @firu-daniel/agent-qa-attrs
+```
+
+## Why an attribute contract rather than test ids scattered by hand
+
+A test that clicks `button.primary:nth-child(2)` breaks on a layout change. A test that clicks the
+button reading "Continue" breaks on a copy change, and breaks in every locale but one. Both failures
+look like a broken feature and are not one.
+
+The alternative is an attribute whose only job is to be stable. That part is well understood. What is
+not is keeping the two sides of it honest: the component that emits the attribute and the test that
+looks it up have to agree on the attribute's name, on what an absent value means, and on how an id is
+composed — and nothing checks that agreement when each side spells it out separately.
+
+This package is that agreement, written once.
+
+## The three families
+
+| Attribute | Carries | Use it when |
+|---|---|---|
+| `data-qa-id` | A stable, human-readable element identifier | Anything a test refers to by name |
+| `data-qa-value` | The asserted value of an element | Visible text is formatted, localized, or otherwise not a reliable assertion target |
+| `data-qa-status` | A coarse lifecycle token — `loading`, `ready`, `error` | A test must wait for a state rather than guess on a spinner |
+
+There is no fourth family, and adding one is a change to this package rather than a new attribute
+name invented at a call site.
+
+## Emitting them
+
+```tsx
+import { qaAttr } from '@firu-daniel/agent-qa-attrs';
+
+<button {...qaAttr({ id: 'login-submit' })}>Continue</button>
+<span {...qaAttr({ id: 'balance', value: balance })}>{formatted}</span>
+<div {...qaAttr({ id: 'upload', status: 'ready' })} />
+```
+
+An option that is not given produces no attribute at all — never an empty-string one, so a test can
+distinguish "no status" from "empty status". `0` and `''` are values like any other: the check is
+against `undefined`, never against falsiness.
+
+## Scoping ids to their feature
+
+Every id carries the area it belongs to, so two features never collide on a bare `submit`. Typing
+that prefix at each call site is a rule someone has to remember; a scope makes it structural.
+
+```tsx
+import { QaScope, useQaAttr } from '@firu-daniel/agent-qa-attrs';
+
+const Submit = () => <button {...useQaAttr({ id: 'submit' })}>Continue</button>;
+
+<QaScope name="login">
+  <Submit /> {/* data-qa-id="login-submit" */}
+</QaScope>;
+```
+
+Scopes nest and extend rather than replace, so a component that carries its own scope can be mounted
+anywhere: a `list` scope inside a `wallet` scope tags `wallet-list-row-3`. `QaScope` renders no
+element of its own, so dropping one into a layout cannot change the DOM a test is driving.
+
+## Reading them back
+
+```ts
+import { qaSelector } from '@firu-daniel/agent-qa-attrs/core';
+
+await page.click(qaSelector({ id: 'login-submit' }));
+await page.waitForSelector(qaSelector({ id: 'upload', status: 'ready' }));
+```
+
+`qaSelector` builds the selector matching exactly what `qaAttr` emits for the same options, so the
+two sides cannot drift: when the contract changes, a hand-written `[data-qa-id="…"]` keeps compiling
+and silently stops matching, and this does not.
+
+The `/core` entry point is framework-agnostic and pulls no React — it is what a test runner, a Node
+script or a non-React application imports.
+
+## Shipping them to production
+
+These attributes are inert `data-*` attributes. They carry no logic, affect no rendering, and are
+deliberately **not** stripped behind an environment flag: an attribute that exists only in a test
+build cannot be relied on by a test that drives the real one.
+
+Their values are test tokens rather than user-visible copy — hardcoded identifier strings, exempt
+from localization by design.
+
+## API
+
+| Export | Entry point | What it does |
+|---|---|---|
+| `qaAttr(options)` | root, `/core` | Builds the attribute bag to spread onto an element |
+| `qaSelector(options)` | root, `/core` | Builds the CSS selector matching what `qaAttr` emits |
+| `joinQaId(prefix, id)` | root, `/core` | Joins an area prefix to a local id |
+| `QA_ATTRIBUTE` | root, `/core` | The three attribute names, spelled once |
+| `QaScope` | root | Declares the area every id beneath it belongs to |
+| `useQaAttr(options)` | root | `qaAttr` with the enclosing scope applied |
+| `useQaScope()` | root | The prefix in effect at this point in the tree |
+
+MIT © firu-daniel

package/dist/chunk-GBT5D3KO.js

@@ -0,0 +1,34 @@
+// src/core/qaAttr.ts
+var QA_ATTRIBUTE = {
+  id: "data-qa-id",
+  value: "data-qa-value",
+  status: "data-qa-status"
+};
+var qaAttr = (options) => {
+  const attributes = { [QA_ATTRIBUTE.id]: options.id };
+  if (options.value !== void 0) {
+    attributes[QA_ATTRIBUTE.value] = String(options.value);
+  }
+  if (options.status !== void 0) {
+    attributes[QA_ATTRIBUTE.status] = options.status;
+  }
+  return attributes;
+};
+var joinQaId = (prefix, id) => prefix === void 0 || prefix === "" ? id : `${prefix}-${id}`;
+
+// src/core/qaSelector.ts
+var escapeAttributeValue = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+var qaSelector = (options) => {
+  let selector = `[${QA_ATTRIBUTE.id}="${escapeAttributeValue(options.id)}"]`;
+  if (options.value !== void 0) {
+    selector += `[${QA_ATTRIBUTE.value}="${escapeAttributeValue(String(options.value))}"]`;
+  }
+  if (options.status !== void 0) {
+    selector += `[${QA_ATTRIBUTE.status}="${escapeAttributeValue(options.status)}"]`;
+  }
+  return selector;
+};
+
+export { QA_ATTRIBUTE, joinQaId, qaAttr, qaSelector };
+//# sourceMappingURL=chunk-GBT5D3KO.js.map
+//# sourceMappingURL=chunk-GBT5D3KO.js.map

package/dist/chunk-GBT5D3KO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/qaAttr.ts","../src/core/qaSelector.ts"],"names":[],"mappings":";AA6CO,IAAM,YAAA,GAAe;AAAA,EAC1B,EAAA,EAAI,YAAA;AAAA,EACJ,KAAA,EAAO,eAAA;AAAA,EACP,MAAA,EAAQ;AACV;AAwBO,IAAM,MAAA,GAAS,CAAC,OAAA,KAAyC;AAC9D,EAAA,MAAM,aAA2B,EAAE,CAAC,aAAa,EAAE,GAAG,QAAQ,EAAA,EAAG;AAEjE,EAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,EAAW;AAC/B,IAAA,UAAA,CAAW,YAAA,CAAa,KAAK,CAAA,GAAI,MAAA,CAAO,QAAQ,KAAK,CAAA;AAAA,EACvD;AAEA,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,UAAA,CAAW,YAAA,CAAa,MAAM,CAAA,GAAI,OAAA,CAAQ,MAAA;AAAA,EAC5C;AAEA,EAAA,OAAO,UAAA;AACT;AAUO,IAAM,QAAA,GAAW,CAAC,MAAA,EAA4B,EAAA,KACnD,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,EAAA,GAAK,EAAA,GAAK,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,EAAE,CAAA;;;ACnF9D,IAAM,oBAAA,GAAuB,CAAC,KAAA,KAA0B,KAAA,CAAM,OAAA,CAAQ,OAAO,MAAM,CAAA,CAAE,OAAA,CAAQ,IAAA,EAAM,KAAK,CAAA;AAWjG,IAAM,UAAA,GAAa,CAAC,OAAA,KAAmC;AAC5D,EAAA,IAAI,QAAA,GAAW,IAAI,YAAA,CAAa,EAAE,KAAK,oBAAA,CAAqB,OAAA,CAAQ,EAAE,CAAC,CAAA,EAAA,CAAA;AAEvE,EAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,EAAW;AAC/B,IAAA,QAAA,IAAY,CAAA,CAAA,EAAI,aAAa,KAAK,CAAA,EAAA,EAAK,qBAAqB,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAC,CAAC,CAAA,EAAA,CAAA;AAAA,EACpF;AAEA,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,QAAA,IAAY,IAAI,YAAA,CAAa,MAAM,KAAK,oBAAA,CAAqB,OAAA,CAAQ,MAAM,CAAC,CAAA,EAAA,CAAA;AAAA,EAC9E;AAEA,EAAA,OAAO,QAAA;AACT","file":"chunk-GBT5D3KO.js","sourcesContent":["/**\n * The `data-qa-*` attribute contract, and the helper that emits it.\n *\n * This is a test affordance, not a styling or behaviour hook: a single,\n * documented way to tag DOM elements with deterministic attributes so a\n * browser-driving agent or an end-to-end test can locate elements, read their\n * state, and assert on values without relying on brittle CSS selectors or on\n * matching user-visible text. A test plan written in terms of these ids is a\n * contract between whoever writes the plan and whoever writes the component.\n *\n * ## The three attribute families (all prefixed `data-qa-`)\n *\n * - `data-qa-id=\"<stable-element-id>\"` — a stable, human-readable identifier\n *   for an element a test needs to find or click (`\"login-submit\"`,\n *   `\"message-input\"`). Keep it unique within a page; for list rows, suffix the\n *   entity id (`\"message-<messageId>\"`).\n * - `data-qa-value=\"<value>\"` — the asserted value of an element when the\n *   visible text is not a reliable assertion target (a formatted balance, a\n *   localized label). Use it when the test must read state, not just presence.\n * - `data-qa-status=\"<state>\"` — a coarse lifecycle token for stateful widgets\n *   (`\"loading\" | \"ready\" | \"error\"`), so a test can wait for a known token\n *   rather than guessing on a spinner.\n *\n * ## Rules\n *\n * - The attributes are **additive and inert**: they never carry business logic,\n *   never affect rendering, and are safe to ship to production. They are\n *   deliberately *not* stripped behind an environment flag — an attribute that\n *   exists only in a test build cannot be relied on by a test that drives the\n *   real one.\n * - Only these three families. A new need extends the contract by a documented\n *   change here, never by a one-off attribute name invented at a call site.\n * - The values are test tokens, not user-visible copy. They are intentionally\n *   hardcoded identifier strings and are exempt from localization by design.\n *\n * ## Usage\n *\n * ```tsx\n * <button {...qaAttr({ id: 'login-submit' })}>Continue</button>\n * <span {...qaAttr({ id: 'balance', value: balance })}>{formatted}</span>\n * <div {...qaAttr({ id: 'upload', status: 'ready' })} />\n * ```\n */\n\n/** The three attribute names this contract defines, spelled once. */\nexport const QA_ATTRIBUTE = {\n  id: 'data-qa-id',\n  value: 'data-qa-value',\n  status: 'data-qa-status',\n} as const;\n\n/** What {@link qaAttr} accepts. Only `id` is required; the rest are emitted when present. */\nexport interface QaAttrOptions {\n  /** Stable, human-readable element identifier (`data-qa-id`). */\n  id: string;\n  /** Asserted value when visible text is not a reliable target (`data-qa-value`). */\n  value?: string | number;\n  /** Coarse lifecycle token, e.g. `loading` | `ready` | `error` (`data-qa-status`). */\n  status?: string;\n}\n\n/** The emitted attribute bag: attribute name to string value, ready to spread onto an element. */\nexport type QaAttributes = Record<string, string>;\n\n/**\n * Build the `data-qa-*` attribute bag to spread onto an element.\n *\n * Only the keys whose option was provided are emitted, so an absent option\n * produces no attribute rather than an empty-string one — a test asserting on\n * `data-qa-status` must be able to distinguish \"no status\" from \"empty status\".\n * `value` is stringified, and `0` and `''` are values like any other: the check\n * is against `undefined`, never against falsiness.\n */\nexport const qaAttr = (options: QaAttrOptions): QaAttributes => {\n  const attributes: QaAttributes = { [QA_ATTRIBUTE.id]: options.id };\n\n  if (options.value !== undefined) {\n    attributes[QA_ATTRIBUTE.value] = String(options.value);\n  }\n\n  if (options.status !== undefined) {\n    attributes[QA_ATTRIBUTE.status] = options.status;\n  }\n\n  return attributes;\n};\n\n/**\n * Join an area prefix and a local id into one contract-shaped id.\n *\n * The naming rule is that an id carries the feature area it belongs to, so two\n * features never collide on a bare `\"submit\"`. An empty or absent prefix\n * returns the local id unchanged, which is what makes an unscoped call site and\n * a scoped one produce the same shape.\n */\nexport const joinQaId = (prefix: string | undefined, id: string): string =>\n  prefix === undefined || prefix === '' ? id : `${prefix}-${id}`;\n","/**\n * The read side of the `data-qa-*` contract: turning the attributes a component\n * emits into the selector a test or a browser-driving agent looks them up by.\n *\n * It exists so the two sides cannot drift. A test that hand-writes\n * `[data-qa-id=\"login-submit\"]` has copied an attribute name that only\n * `qaAttr` should know; when the contract gains or renames a family, the\n * hand-written selector keeps compiling and silently stops matching.\n */\n\nimport { QA_ATTRIBUTE, type QaAttrOptions } from './qaAttr.js';\n\n/** Escape a value for use inside a CSS attribute selector's quoted string. */\nconst escapeAttributeValue = (value: string): string => value.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"');\n\n/**\n * Build a CSS attribute selector matching the elements {@link qaAttr} would\n * emit for the same options.\n *\n * Every provided option narrows the selector, in the contract's own order, so\n * `{ id: 'upload', status: 'ready' }` yields\n * `[data-qa-id=\"upload\"][data-qa-status=\"ready\"]` — the \"wait until this\n * element reaches this state\" query, expressed once.\n */\nexport const qaSelector = (options: QaAttrOptions): string => {\n  let selector = `[${QA_ATTRIBUTE.id}=\"${escapeAttributeValue(options.id)}\"]`;\n\n  if (options.value !== undefined) {\n    selector += `[${QA_ATTRIBUTE.value}=\"${escapeAttributeValue(String(options.value))}\"]`;\n  }\n\n  if (options.status !== undefined) {\n    selector += `[${QA_ATTRIBUTE.status}=\"${escapeAttributeValue(options.status)}\"]`;\n  }\n\n  return selector;\n};\n"]}

package/dist/core/index.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+// src/core/qaAttr.ts
+var QA_ATTRIBUTE = {
+  id: "data-qa-id",
+  value: "data-qa-value",
+  status: "data-qa-status"
+};
+var qaAttr = (options) => {
+  const attributes = { [QA_ATTRIBUTE.id]: options.id };
+  if (options.value !== void 0) {
+    attributes[QA_ATTRIBUTE.value] = String(options.value);
+  }
+  if (options.status !== void 0) {
+    attributes[QA_ATTRIBUTE.status] = options.status;
+  }
+  return attributes;
+};
+var joinQaId = (prefix, id) => prefix === void 0 || prefix === "" ? id : `${prefix}-${id}`;
+
+// src/core/qaSelector.ts
+var escapeAttributeValue = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+var qaSelector = (options) => {
+  let selector = `[${QA_ATTRIBUTE.id}="${escapeAttributeValue(options.id)}"]`;
+  if (options.value !== void 0) {
+    selector += `[${QA_ATTRIBUTE.value}="${escapeAttributeValue(String(options.value))}"]`;
+  }
+  if (options.status !== void 0) {
+    selector += `[${QA_ATTRIBUTE.status}="${escapeAttributeValue(options.status)}"]`;
+  }
+  return selector;
+};
+
+exports.QA_ATTRIBUTE = QA_ATTRIBUTE;
+exports.joinQaId = joinQaId;
+exports.qaAttr = qaAttr;
+exports.qaSelector = qaSelector;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/qaAttr.ts","../../src/core/qaSelector.ts"],"names":[],"mappings":";;;AA6CO,IAAM,YAAA,GAAe;AAAA,EAC1B,EAAA,EAAI,YAAA;AAAA,EACJ,KAAA,EAAO,eAAA;AAAA,EACP,MAAA,EAAQ;AACV;AAwBO,IAAM,MAAA,GAAS,CAAC,OAAA,KAAyC;AAC9D,EAAA,MAAM,aAA2B,EAAE,CAAC,aAAa,EAAE,GAAG,QAAQ,EAAA,EAAG;AAEjE,EAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,EAAW;AAC/B,IAAA,UAAA,CAAW,YAAA,CAAa,KAAK,CAAA,GAAI,MAAA,CAAO,QAAQ,KAAK,CAAA;AAAA,EACvD;AAEA,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,UAAA,CAAW,YAAA,CAAa,MAAM,CAAA,GAAI,OAAA,CAAQ,MAAA;AAAA,EAC5C;AAEA,EAAA,OAAO,UAAA;AACT;AAUO,IAAM,QAAA,GAAW,CAAC,MAAA,EAA4B,EAAA,KACnD,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,EAAA,GAAK,EAAA,GAAK,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,EAAE,CAAA;;;ACnF9D,IAAM,oBAAA,GAAuB,CAAC,KAAA,KAA0B,KAAA,CAAM,OAAA,CAAQ,OAAO,MAAM,CAAA,CAAE,OAAA,CAAQ,IAAA,EAAM,KAAK,CAAA;AAWjG,IAAM,UAAA,GAAa,CAAC,OAAA,KAAmC;AAC5D,EAAA,IAAI,QAAA,GAAW,IAAI,YAAA,CAAa,EAAE,KAAK,oBAAA,CAAqB,OAAA,CAAQ,EAAE,CAAC,CAAA,EAAA,CAAA;AAEvE,EAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,EAAW;AAC/B,IAAA,QAAA,IAAY,CAAA,CAAA,EAAI,aAAa,KAAK,CAAA,EAAA,EAAK,qBAAqB,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAC,CAAC,CAAA,EAAA,CAAA;AAAA,EACpF;AAEA,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,QAAA,IAAY,IAAI,YAAA,CAAa,MAAM,KAAK,oBAAA,CAAqB,OAAA,CAAQ,MAAM,CAAC,CAAA,EAAA,CAAA;AAAA,EAC9E;AAEA,EAAA,OAAO,QAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * The `data-qa-*` attribute contract, and the helper that emits it.\n *\n * This is a test affordance, not a styling or behaviour hook: a single,\n * documented way to tag DOM elements with deterministic attributes so a\n * browser-driving agent or an end-to-end test can locate elements, read their\n * state, and assert on values without relying on brittle CSS selectors or on\n * matching user-visible text. A test plan written in terms of these ids is a\n * contract between whoever writes the plan and whoever writes the component.\n *\n * ## The three attribute families (all prefixed `data-qa-`)\n *\n * - `data-qa-id=\"<stable-element-id>\"` — a stable, human-readable identifier\n *   for an element a test needs to find or click (`\"login-submit\"`,\n *   `\"message-input\"`). Keep it unique within a page; for list rows, suffix the\n *   entity id (`\"message-<messageId>\"`).\n * - `data-qa-value=\"<value>\"` — the asserted value of an element when the\n *   visible text is not a reliable assertion target (a formatted balance, a\n *   localized label). Use it when the test must read state, not just presence.\n * - `data-qa-status=\"<state>\"` — a coarse lifecycle token for stateful widgets\n *   (`\"loading\" | \"ready\" | \"error\"`), so a test can wait for a known token\n *   rather than guessing on a spinner.\n *\n * ## Rules\n *\n * - The attributes are **additive and inert**: they never carry business logic,\n *   never affect rendering, and are safe to ship to production. They are\n *   deliberately *not* stripped behind an environment flag — an attribute that\n *   exists only in a test build cannot be relied on by a test that drives the\n *   real one.\n * - Only these three families. A new need extends the contract by a documented\n *   change here, never by a one-off attribute name invented at a call site.\n * - The values are test tokens, not user-visible copy. They are intentionally\n *   hardcoded identifier strings and are exempt from localization by design.\n *\n * ## Usage\n *\n * ```tsx\n * <button {...qaAttr({ id: 'login-submit' })}>Continue</button>\n * <span {...qaAttr({ id: 'balance', value: balance })}>{formatted}</span>\n * <div {...qaAttr({ id: 'upload', status: 'ready' })} />\n * ```\n */\n\n/** The three attribute names this contract defines, spelled once. */\nexport const QA_ATTRIBUTE = {\n  id: 'data-qa-id',\n  value: 'data-qa-value',\n  status: 'data-qa-status',\n} as const;\n\n/** What {@link qaAttr} accepts. Only `id` is required; the rest are emitted when present. */\nexport interface QaAttrOptions {\n  /** Stable, human-readable element identifier (`data-qa-id`). */\n  id: string;\n  /** Asserted value when visible text is not a reliable target (`data-qa-value`). */\n  value?: string | number;\n  /** Coarse lifecycle token, e.g. `loading` | `ready` | `error` (`data-qa-status`). */\n  status?: string;\n}\n\n/** The emitted attribute bag: attribute name to string value, ready to spread onto an element. */\nexport type QaAttributes = Record<string, string>;\n\n/**\n * Build the `data-qa-*` attribute bag to spread onto an element.\n *\n * Only the keys whose option was provided are emitted, so an absent option\n * produces no attribute rather than an empty-string one — a test asserting on\n * `data-qa-status` must be able to distinguish \"no status\" from \"empty status\".\n * `value` is stringified, and `0` and `''` are values like any other: the check\n * is against `undefined`, never against falsiness.\n */\nexport const qaAttr = (options: QaAttrOptions): QaAttributes => {\n  const attributes: QaAttributes = { [QA_ATTRIBUTE.id]: options.id };\n\n  if (options.value !== undefined) {\n    attributes[QA_ATTRIBUTE.value] = String(options.value);\n  }\n\n  if (options.status !== undefined) {\n    attributes[QA_ATTRIBUTE.status] = options.status;\n  }\n\n  return attributes;\n};\n\n/**\n * Join an area prefix and a local id into one contract-shaped id.\n *\n * The naming rule is that an id carries the feature area it belongs to, so two\n * features never collide on a bare `\"submit\"`. An empty or absent prefix\n * returns the local id unchanged, which is what makes an unscoped call site and\n * a scoped one produce the same shape.\n */\nexport const joinQaId = (prefix: string | undefined, id: string): string =>\n  prefix === undefined || prefix === '' ? id : `${prefix}-${id}`;\n","/**\n * The read side of the `data-qa-*` contract: turning the attributes a component\n * emits into the selector a test or a browser-driving agent looks them up by.\n *\n * It exists so the two sides cannot drift. A test that hand-writes\n * `[data-qa-id=\"login-submit\"]` has copied an attribute name that only\n * `qaAttr` should know; when the contract gains or renames a family, the\n * hand-written selector keeps compiling and silently stops matching.\n */\n\nimport { QA_ATTRIBUTE, type QaAttrOptions } from './qaAttr.js';\n\n/** Escape a value for use inside a CSS attribute selector's quoted string. */\nconst escapeAttributeValue = (value: string): string => value.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"');\n\n/**\n * Build a CSS attribute selector matching the elements {@link qaAttr} would\n * emit for the same options.\n *\n * Every provided option narrows the selector, in the contract's own order, so\n * `{ id: 'upload', status: 'ready' }` yields\n * `[data-qa-id=\"upload\"][data-qa-status=\"ready\"]` — the \"wait until this\n * element reaches this state\" query, expressed once.\n */\nexport const qaSelector = (options: QaAttrOptions): string => {\n  let selector = `[${QA_ATTRIBUTE.id}=\"${escapeAttributeValue(options.id)}\"]`;\n\n  if (options.value !== undefined) {\n    selector += `[${QA_ATTRIBUTE.value}=\"${escapeAttributeValue(String(options.value))}\"]`;\n  }\n\n  if (options.status !== undefined) {\n    selector += `[${QA_ATTRIBUTE.status}=\"${escapeAttributeValue(options.status)}\"]`;\n  }\n\n  return selector;\n};\n"]}

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The framework-agnostic half of the contract: the attribute names, the helper
+ * that emits them, and the selector that reads them back. Nothing here imports
+ * a rendering library, so a test runner, a Node script or a non-React
+ * application can depend on `@firu-daniel/agent-qa-attrs/core` alone.
+ */
+export { QA_ATTRIBUTE, qaAttr, joinQaId } from './qaAttr.js';
+export type { QaAttrOptions, QaAttributes } from './qaAttr.js';
+export { qaSelector } from './qaSelector.js';

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { QA_ATTRIBUTE, joinQaId, qaAttr, qaSelector } from '../chunk-GBT5D3KO.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/core/qaAttr.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The `data-qa-*` attribute contract, and the helper that emits it.
+ *
+ * This is a test affordance, not a styling or behaviour hook: a single,
+ * documented way to tag DOM elements with deterministic attributes so a
+ * browser-driving agent or an end-to-end test can locate elements, read their
+ * state, and assert on values without relying on brittle CSS selectors or on
+ * matching user-visible text. A test plan written in terms of these ids is a
+ * contract between whoever writes the plan and whoever writes the component.
+ *
+ * ## The three attribute families (all prefixed `data-qa-`)
+ *
+ * - `data-qa-id="<stable-element-id>"` — a stable, human-readable identifier
+ *   for an element a test needs to find or click (`"login-submit"`,
+ *   `"message-input"`). Keep it unique within a page; for list rows, suffix the
+ *   entity id (`"message-<messageId>"`).
+ * - `data-qa-value="<value>"` — the asserted value of an element when the
+ *   visible text is not a reliable assertion target (a formatted balance, a
+ *   localized label). Use it when the test must read state, not just presence.
+ * - `data-qa-status="<state>"` — a coarse lifecycle token for stateful widgets
+ *   (`"loading" | "ready" | "error"`), so a test can wait for a known token
+ *   rather than guessing on a spinner.
+ *
+ * ## Rules
+ *
+ * - The attributes are **additive and inert**: they never carry business logic,
+ *   never affect rendering, and are safe to ship to production. They are
+ *   deliberately *not* stripped behind an environment flag — an attribute that
+ *   exists only in a test build cannot be relied on by a test that drives the
+ *   real one.
+ * - Only these three families. A new need extends the contract by a documented
+ *   change here, never by a one-off attribute name invented at a call site.
+ * - The values are test tokens, not user-visible copy. They are intentionally
+ *   hardcoded identifier strings and are exempt from localization by design.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <button {...qaAttr({ id: 'login-submit' })}>Continue</button>
+ * <span {...qaAttr({ id: 'balance', value: balance })}>{formatted}</span>
+ * <div {...qaAttr({ id: 'upload', status: 'ready' })} />
+ * ```
+ */
+/** The three attribute names this contract defines, spelled once. */
+export declare const QA_ATTRIBUTE: {
+    readonly id: "data-qa-id";
+    readonly value: "data-qa-value";
+    readonly status: "data-qa-status";
+};
+/** What {@link qaAttr} accepts. Only `id` is required; the rest are emitted when present. */
+export interface QaAttrOptions {
+    /** Stable, human-readable element identifier (`data-qa-id`). */
+    id: string;
+    /** Asserted value when visible text is not a reliable target (`data-qa-value`). */
+    value?: string | number;
+    /** Coarse lifecycle token, e.g. `loading` | `ready` | `error` (`data-qa-status`). */
+    status?: string;
+}
+/** The emitted attribute bag: attribute name to string value, ready to spread onto an element. */
+export type QaAttributes = Record<string, string>;
+/**
+ * Build the `data-qa-*` attribute bag to spread onto an element.
+ *
+ * Only the keys whose option was provided are emitted, so an absent option
+ * produces no attribute rather than an empty-string one — a test asserting on
+ * `data-qa-status` must be able to distinguish "no status" from "empty status".
+ * `value` is stringified, and `0` and `''` are values like any other: the check
+ * is against `undefined`, never against falsiness.
+ */
+export declare const qaAttr: (options: QaAttrOptions) => QaAttributes;
+/**
+ * Join an area prefix and a local id into one contract-shaped id.
+ *
+ * The naming rule is that an id carries the feature area it belongs to, so two
+ * features never collide on a bare `"submit"`. An empty or absent prefix
+ * returns the local id unchanged, which is what makes an unscoped call site and
+ * a scoped one produce the same shape.
+ */
+export declare const joinQaId: (prefix: string | undefined, id: string) => string;

package/dist/core/qaSelector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The read side of the `data-qa-*` contract: turning the attributes a component
+ * emits into the selector a test or a browser-driving agent looks them up by.
+ *
+ * It exists so the two sides cannot drift. A test that hand-writes
+ * `[data-qa-id="login-submit"]` has copied an attribute name that only
+ * `qaAttr` should know; when the contract gains or renames a family, the
+ * hand-written selector keeps compiling and silently stops matching.
+ */
+import { type QaAttrOptions } from './qaAttr.js';
+/**
+ * Build a CSS attribute selector matching the elements {@link qaAttr} would
+ * emit for the same options.
+ *
+ * Every provided option narrows the selector, in the contract's own order, so
+ * `{ id: 'upload', status: 'ready' }` yields
+ * `[data-qa-id="upload"][data-qa-status="ready"]` — the "wait until this
+ * element reaches this state" query, expressed once.
+ */
+export declare const qaSelector: (options: QaAttrOptions) => string;

package/dist/index.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+var react = require('react');
+
+// src/core/qaAttr.ts
+var QA_ATTRIBUTE = {
+  id: "data-qa-id",
+  value: "data-qa-value",
+  status: "data-qa-status"
+};
+var qaAttr = (options) => {
+  const attributes = { [QA_ATTRIBUTE.id]: options.id };
+  if (options.value !== void 0) {
+    attributes[QA_ATTRIBUTE.value] = String(options.value);
+  }
+  if (options.status !== void 0) {
+    attributes[QA_ATTRIBUTE.status] = options.status;
+  }
+  return attributes;
+};
+var joinQaId = (prefix, id) => prefix === void 0 || prefix === "" ? id : `${prefix}-${id}`;
+
+// src/core/qaSelector.ts
+var escapeAttributeValue = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+var qaSelector = (options) => {
+  let selector = `[${QA_ATTRIBUTE.id}="${escapeAttributeValue(options.id)}"]`;
+  if (options.value !== void 0) {
+    selector += `[${QA_ATTRIBUTE.value}="${escapeAttributeValue(String(options.value))}"]`;
+  }
+  if (options.status !== void 0) {
+    selector += `[${QA_ATTRIBUTE.status}="${escapeAttributeValue(options.status)}"]`;
+  }
+  return selector;
+};
+var QaScopeContext = react.createContext(void 0);
+var QaScope = ({ name, children }) => {
+  const parent = react.useContext(QaScopeContext);
+  const value = react.useMemo(() => joinQaId(parent, name), [parent, name]);
+  return react.createElement(QaScopeContext.Provider, { value }, children);
+};
+var useQaScope = () => react.useContext(QaScopeContext);
+var useQaAttr = (options) => {
+  const prefix = useQaScope();
+  const { id, value, status } = options;
+  return react.useMemo(() => qaAttr({ id: joinQaId(prefix, id), value, status }), [prefix, id, value, status]);
+};
+
+exports.QA_ATTRIBUTE = QA_ATTRIBUTE;
+exports.QaScope = QaScope;
+exports.joinQaId = joinQaId;
+exports.qaAttr = qaAttr;
+exports.qaSelector = qaSelector;
+exports.useQaAttr = useQaAttr;
+exports.useQaScope = useQaScope;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/qaAttr.ts","../src/core/qaSelector.ts","../src/react/QaScope.tsx"],"names":["createContext","useContext","useMemo","createElement"],"mappings":";;;;;AA6CO,IAAM,YAAA,GAAe;AAAA,EAC1B,EAAA,EAAI,YAAA;AAAA,EACJ,KAAA,EAAO,eAAA;AAAA,EACP,MAAA,EAAQ;AACV;AAwBO,IAAM,MAAA,GAAS,CAAC,OAAA,KAAyC;AAC9D,EAAA,MAAM,aAA2B,EAAE,CAAC,aAAa,EAAE,GAAG,QAAQ,EAAA,EAAG;AAEjE,EAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,EAAW;AAC/B,IAAA,UAAA,CAAW,YAAA,CAAa,KAAK,CAAA,GAAI,MAAA,CAAO,QAAQ,KAAK,CAAA;AAAA,EACvD;AAEA,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,UAAA,CAAW,YAAA,CAAa,MAAM,CAAA,GAAI,OAAA,CAAQ,MAAA;AAAA,EAC5C;AAEA,EAAA,OAAO,UAAA;AACT;AAUO,IAAM,QAAA,GAAW,CAAC,MAAA,EAA4B,EAAA,KACnD,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,EAAA,GAAK,EAAA,GAAK,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,EAAE,CAAA;;;ACnF9D,IAAM,oBAAA,GAAuB,CAAC,KAAA,KAA0B,KAAA,CAAM,OAAA,CAAQ,OAAO,MAAM,CAAA,CAAE,OAAA,CAAQ,IAAA,EAAM,KAAK,CAAA;AAWjG,IAAM,UAAA,GAAa,CAAC,OAAA,KAAmC;AAC5D,EAAA,IAAI,QAAA,GAAW,IAAI,YAAA,CAAa,EAAE,KAAK,oBAAA,CAAqB,OAAA,CAAQ,EAAE,CAAC,CAAA,EAAA,CAAA;AAEvE,EAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,EAAW;AAC/B,IAAA,QAAA,IAAY,CAAA,CAAA,EAAI,aAAa,KAAK,CAAA,EAAA,EAAK,qBAAqB,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAC,CAAC,CAAA,EAAA,CAAA;AAAA,EACpF;AAEA,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,QAAA,IAAY,IAAI,YAAA,CAAa,MAAM,KAAK,oBAAA,CAAqB,OAAA,CAAQ,MAAM,CAAC,CAAA,EAAA,CAAA;AAAA,EAC9E;AAEA,EAAA,OAAO,QAAA;AACT;ACdA,IAAM,cAAA,GAAiBA,oBAAkC,MAAS,CAAA;AAkB3D,IAAM,OAAA,GAAU,CAAC,EAAE,IAAA,EAAM,UAAS,KAAoB;AAC3D,EAAA,MAAM,MAAA,GAASC,iBAAW,cAAc,CAAA;AACxC,EAAA,MAAM,KAAA,GAAQC,aAAA,CAAQ,MAAM,QAAA,CAAS,MAAA,EAAQ,IAAI,CAAA,EAAG,CAAC,MAAA,EAAQ,IAAI,CAAC,CAAA;AAElE,EAAA,OAAOC,oBAAc,cAAA,CAAe,QAAA,EAAU,EAAE,KAAA,IAAS,QAAQ,CAAA;AACnE;AAQO,IAAM,UAAA,GAAa,MAA0BF,gBAAA,CAAW,cAAc;AAStE,IAAM,SAAA,GAAY,CAAC,OAAA,KAAyC;AACjE,EAAA,MAAM,SAAS,UAAA,EAAW;AAC1B,EAAA,MAAM,EAAE,EAAA,EAAI,KAAA,EAAO,MAAA,EAAO,GAAI,OAAA;AAE9B,EAAA,OAAOC,cAAQ,MAAM,MAAA,CAAO,EAAE,EAAA,EAAI,QAAA,CAAS,QAAQ,EAAE,CAAA,EAAG,KAAA,EAAO,MAAA,EAAQ,CAAA,EAAG,CAAC,QAAQ,EAAA,EAAI,KAAA,EAAO,MAAM,CAAC,CAAA;AACvG","file":"index.cjs","sourcesContent":["/**\n * The `data-qa-*` attribute contract, and the helper that emits it.\n *\n * This is a test affordance, not a styling or behaviour hook: a single,\n * documented way to tag DOM elements with deterministic attributes so a\n * browser-driving agent or an end-to-end test can locate elements, read their\n * state, and assert on values without relying on brittle CSS selectors or on\n * matching user-visible text. A test plan written in terms of these ids is a\n * contract between whoever writes the plan and whoever writes the component.\n *\n * ## The three attribute families (all prefixed `data-qa-`)\n *\n * - `data-qa-id=\"<stable-element-id>\"` — a stable, human-readable identifier\n *   for an element a test needs to find or click (`\"login-submit\"`,\n *   `\"message-input\"`). Keep it unique within a page; for list rows, suffix the\n *   entity id (`\"message-<messageId>\"`).\n * - `data-qa-value=\"<value>\"` — the asserted value of an element when the\n *   visible text is not a reliable assertion target (a formatted balance, a\n *   localized label). Use it when the test must read state, not just presence.\n * - `data-qa-status=\"<state>\"` — a coarse lifecycle token for stateful widgets\n *   (`\"loading\" | \"ready\" | \"error\"`), so a test can wait for a known token\n *   rather than guessing on a spinner.\n *\n * ## Rules\n *\n * - The attributes are **additive and inert**: they never carry business logic,\n *   never affect rendering, and are safe to ship to production. They are\n *   deliberately *not* stripped behind an environment flag — an attribute that\n *   exists only in a test build cannot be relied on by a test that drives the\n *   real one.\n * - Only these three families. A new need extends the contract by a documented\n *   change here, never by a one-off attribute name invented at a call site.\n * - The values are test tokens, not user-visible copy. They are intentionally\n *   hardcoded identifier strings and are exempt from localization by design.\n *\n * ## Usage\n *\n * ```tsx\n * <button {...qaAttr({ id: 'login-submit' })}>Continue</button>\n * <span {...qaAttr({ id: 'balance', value: balance })}>{formatted}</span>\n * <div {...qaAttr({ id: 'upload', status: 'ready' })} />\n * ```\n */\n\n/** The three attribute names this contract defines, spelled once. */\nexport const QA_ATTRIBUTE = {\n  id: 'data-qa-id',\n  value: 'data-qa-value',\n  status: 'data-qa-status',\n} as const;\n\n/** What {@link qaAttr} accepts. Only `id` is required; the rest are emitted when present. */\nexport interface QaAttrOptions {\n  /** Stable, human-readable element identifier (`data-qa-id`). */\n  id: string;\n  /** Asserted value when visible text is not a reliable target (`data-qa-value`). */\n  value?: string | number;\n  /** Coarse lifecycle token, e.g. `loading` | `ready` | `error` (`data-qa-status`). */\n  status?: string;\n}\n\n/** The emitted attribute bag: attribute name to string value, ready to spread onto an element. */\nexport type QaAttributes = Record<string, string>;\n\n/**\n * Build the `data-qa-*` attribute bag to spread onto an element.\n *\n * Only the keys whose option was provided are emitted, so an absent option\n * produces no attribute rather than an empty-string one — a test asserting on\n * `data-qa-status` must be able to distinguish \"no status\" from \"empty status\".\n * `value` is stringified, and `0` and `''` are values like any other: the check\n * is against `undefined`, never against falsiness.\n */\nexport const qaAttr = (options: QaAttrOptions): QaAttributes => {\n  const attributes: QaAttributes = { [QA_ATTRIBUTE.id]: options.id };\n\n  if (options.value !== undefined) {\n    attributes[QA_ATTRIBUTE.value] = String(options.value);\n  }\n\n  if (options.status !== undefined) {\n    attributes[QA_ATTRIBUTE.status] = options.status;\n  }\n\n  return attributes;\n};\n\n/**\n * Join an area prefix and a local id into one contract-shaped id.\n *\n * The naming rule is that an id carries the feature area it belongs to, so two\n * features never collide on a bare `\"submit\"`. An empty or absent prefix\n * returns the local id unchanged, which is what makes an unscoped call site and\n * a scoped one produce the same shape.\n */\nexport const joinQaId = (prefix: string | undefined, id: string): string =>\n  prefix === undefined || prefix === '' ? id : `${prefix}-${id}`;\n","/**\n * The read side of the `data-qa-*` contract: turning the attributes a component\n * emits into the selector a test or a browser-driving agent looks them up by.\n *\n * It exists so the two sides cannot drift. A test that hand-writes\n * `[data-qa-id=\"login-submit\"]` has copied an attribute name that only\n * `qaAttr` should know; when the contract gains or renames a family, the\n * hand-written selector keeps compiling and silently stops matching.\n */\n\nimport { QA_ATTRIBUTE, type QaAttrOptions } from './qaAttr.js';\n\n/** Escape a value for use inside a CSS attribute selector's quoted string. */\nconst escapeAttributeValue = (value: string): string => value.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"');\n\n/**\n * Build a CSS attribute selector matching the elements {@link qaAttr} would\n * emit for the same options.\n *\n * Every provided option narrows the selector, in the contract's own order, so\n * `{ id: 'upload', status: 'ready' }` yields\n * `[data-qa-id=\"upload\"][data-qa-status=\"ready\"]` — the \"wait until this\n * element reaches this state\" query, expressed once.\n */\nexport const qaSelector = (options: QaAttrOptions): string => {\n  let selector = `[${QA_ATTRIBUTE.id}=\"${escapeAttributeValue(options.id)}\"]`;\n\n  if (options.value !== undefined) {\n    selector += `[${QA_ATTRIBUTE.value}=\"${escapeAttributeValue(String(options.value))}\"]`;\n  }\n\n  if (options.status !== undefined) {\n    selector += `[${QA_ATTRIBUTE.status}=\"${escapeAttributeValue(options.status)}\"]`;\n  }\n\n  return selector;\n};\n","/**\n * The React binding: an area prefix that travels down the tree, so a call site\n * names only the element it is tagging.\n *\n * The contract's naming rule — every id carries the feature area it belongs to,\n * so two features never collide on a bare `\"submit\"` — is a rule a call site\n * has to remember on its own the moment the prefix is typed by hand. A scope\n * makes the prefix structural instead: a feature declares its area once, and\n * every `useQaAttr` beneath it emits `\"<area>-<id>\"` whether or not whoever\n * wrote that line was thinking about the convention.\n *\n * Scopes nest, and a nested scope extends rather than replaces its parent's\n * prefix: a `list` scope inside a `wallet` scope tags `\"wallet-list-row-3\"`.\n * That is what lets a component that is reused in two places carry its own\n * scope without deciding where it will be mounted.\n */\n\nimport { createContext, createElement, useContext, useMemo, type ReactNode } from 'react';\n\nimport { joinQaId, qaAttr, type QaAttributes, type QaAttrOptions } from '../core/qaAttr.js';\n\n/** The prefix in effect for the subtree, or `undefined` at the root where there is none. */\nconst QaScopeContext = createContext<string | undefined>(undefined);\n\nexport interface QaScopeProps {\n  /**\n   * The area name contributed by this scope, joined to any enclosing one.\n   * An empty name contributes nothing, which is what makes a conditionally\n   * scoped component legal without a second code path.\n   */\n  name: string;\n  children: ReactNode;\n}\n\n/**\n * Declare the area every `data-qa-id` beneath this point belongs to.\n *\n * It renders no element of its own — it is a context provider and nothing else,\n * so dropping one into a layout can never change the DOM a test is driving.\n */\nexport const QaScope = ({ name, children }: QaScopeProps) => {\n  const parent = useContext(QaScopeContext);\n  const value = useMemo(() => joinQaId(parent, name), [parent, name]);\n\n  return createElement(QaScopeContext.Provider, { value }, children);\n};\n\n/**\n * The prefix in effect at this point in the tree, or `undefined` outside every\n * scope. Exposed for the case a component needs the id string itself — a test\n * hook that reports which element it will drive, for instance — rather than the\n * attribute bag.\n */\nexport const useQaScope = (): string | undefined => useContext(QaScopeContext);\n\n/**\n * Build the `data-qa-*` attribute bag for an element, with the enclosing scope's\n * area already applied to its id.\n *\n * Outside any scope it is exactly `qaAttr`, so a component is free to use it\n * before anyone has decided whether the feature around it gets a scope.\n */\nexport const useQaAttr = (options: QaAttrOptions): QaAttributes => {\n  const prefix = useQaScope();\n  const { id, value, status } = options;\n\n  return useMemo(() => qaAttr({ id: joinQaId(prefix, id), value, status }), [prefix, id, value, status]);\n};\n"]}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@firu-daniel/agent-qa-attrs` — the `data-qa-*` contract that makes an
+ * application deterministically drivable by browser-driving agents and
+ * end-to-end tests.
+ *
+ * This entry point carries both halves. Consumers with no React dependency —
+ * a test runner, a Node script — import `@firu-daniel/agent-qa-attrs/core`
+ * instead, which pulls none of it.
+ */
+export * from './core/index.js';
+export * from './react/index.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+import { joinQaId, qaAttr } from './chunk-GBT5D3KO.js';
+export { QA_ATTRIBUTE, joinQaId, qaAttr, qaSelector } from './chunk-GBT5D3KO.js';
+import { createContext, useContext, useMemo, createElement } from 'react';
+
+var QaScopeContext = createContext(void 0);
+var QaScope = ({ name, children }) => {
+  const parent = useContext(QaScopeContext);
+  const value = useMemo(() => joinQaId(parent, name), [parent, name]);
+  return createElement(QaScopeContext.Provider, { value }, children);
+};
+var useQaScope = () => useContext(QaScopeContext);
+var useQaAttr = (options) => {
+  const prefix = useQaScope();
+  const { id, value, status } = options;
+  return useMemo(() => qaAttr({ id: joinQaId(prefix, id), value, status }), [prefix, id, value, status]);
+};
+
+export { QaScope, useQaAttr, useQaScope };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/QaScope.tsx"],"names":[],"mappings":";;;;AAsBA,IAAM,cAAA,GAAiB,cAAkC,MAAS,CAAA;AAkB3D,IAAM,OAAA,GAAU,CAAC,EAAE,IAAA,EAAM,UAAS,KAAoB;AAC3D,EAAA,MAAM,MAAA,GAAS,WAAW,cAAc,CAAA;AACxC,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,MAAM,QAAA,CAAS,MAAA,EAAQ,IAAI,CAAA,EAAG,CAAC,MAAA,EAAQ,IAAI,CAAC,CAAA;AAElE,EAAA,OAAO,cAAc,cAAA,CAAe,QAAA,EAAU,EAAE,KAAA,IAAS,QAAQ,CAAA;AACnE;AAQO,IAAM,UAAA,GAAa,MAA0B,UAAA,CAAW,cAAc;AAStE,IAAM,SAAA,GAAY,CAAC,OAAA,KAAyC;AACjE,EAAA,MAAM,SAAS,UAAA,EAAW;AAC1B,EAAA,MAAM,EAAE,EAAA,EAAI,KAAA,EAAO,MAAA,EAAO,GAAI,OAAA;AAE9B,EAAA,OAAO,QAAQ,MAAM,MAAA,CAAO,EAAE,EAAA,EAAI,QAAA,CAAS,QAAQ,EAAE,CAAA,EAAG,KAAA,EAAO,MAAA,EAAQ,CAAA,EAAG,CAAC,QAAQ,EAAA,EAAI,KAAA,EAAO,MAAM,CAAC,CAAA;AACvG","file":"index.js","sourcesContent":["/**\n * The React binding: an area prefix that travels down the tree, so a call site\n * names only the element it is tagging.\n *\n * The contract's naming rule — every id carries the feature area it belongs to,\n * so two features never collide on a bare `\"submit\"` — is a rule a call site\n * has to remember on its own the moment the prefix is typed by hand. A scope\n * makes the prefix structural instead: a feature declares its area once, and\n * every `useQaAttr` beneath it emits `\"<area>-<id>\"` whether or not whoever\n * wrote that line was thinking about the convention.\n *\n * Scopes nest, and a nested scope extends rather than replaces its parent's\n * prefix: a `list` scope inside a `wallet` scope tags `\"wallet-list-row-3\"`.\n * That is what lets a component that is reused in two places carry its own\n * scope without deciding where it will be mounted.\n */\n\nimport { createContext, createElement, useContext, useMemo, type ReactNode } from 'react';\n\nimport { joinQaId, qaAttr, type QaAttributes, type QaAttrOptions } from '../core/qaAttr.js';\n\n/** The prefix in effect for the subtree, or `undefined` at the root where there is none. */\nconst QaScopeContext = createContext<string | undefined>(undefined);\n\nexport interface QaScopeProps {\n  /**\n   * The area name contributed by this scope, joined to any enclosing one.\n   * An empty name contributes nothing, which is what makes a conditionally\n   * scoped component legal without a second code path.\n   */\n  name: string;\n  children: ReactNode;\n}\n\n/**\n * Declare the area every `data-qa-id` beneath this point belongs to.\n *\n * It renders no element of its own — it is a context provider and nothing else,\n * so dropping one into a layout can never change the DOM a test is driving.\n */\nexport const QaScope = ({ name, children }: QaScopeProps) => {\n  const parent = useContext(QaScopeContext);\n  const value = useMemo(() => joinQaId(parent, name), [parent, name]);\n\n  return createElement(QaScopeContext.Provider, { value }, children);\n};\n\n/**\n * The prefix in effect at this point in the tree, or `undefined` outside every\n * scope. Exposed for the case a component needs the id string itself — a test\n * hook that reports which element it will drive, for instance — rather than the\n * attribute bag.\n */\nexport const useQaScope = (): string | undefined => useContext(QaScopeContext);\n\n/**\n * Build the `data-qa-*` attribute bag for an element, with the enclosing scope's\n * area already applied to its id.\n *\n * Outside any scope it is exactly `qaAttr`, so a component is free to use it\n * before anyone has decided whether the feature around it gets a scope.\n */\nexport const useQaAttr = (options: QaAttrOptions): QaAttributes => {\n  const prefix = useQaScope();\n  const { id, value, status } = options;\n\n  return useMemo(() => qaAttr({ id: joinQaId(prefix, id), value, status }), [prefix, id, value, status]);\n};\n"]}

package/dist/react/QaScope.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The React binding: an area prefix that travels down the tree, so a call site
+ * names only the element it is tagging.
+ *
+ * The contract's naming rule — every id carries the feature area it belongs to,
+ * so two features never collide on a bare `"submit"` — is a rule a call site
+ * has to remember on its own the moment the prefix is typed by hand. A scope
+ * makes the prefix structural instead: a feature declares its area once, and
+ * every `useQaAttr` beneath it emits `"<area>-<id>"` whether or not whoever
+ * wrote that line was thinking about the convention.
+ *
+ * Scopes nest, and a nested scope extends rather than replaces its parent's
+ * prefix: a `list` scope inside a `wallet` scope tags `"wallet-list-row-3"`.
+ * That is what lets a component that is reused in two places carry its own
+ * scope without deciding where it will be mounted.
+ */
+import { type ReactNode } from 'react';
+import { type QaAttributes, type QaAttrOptions } from '../core/qaAttr.js';
+export interface QaScopeProps {
+    /**
+     * The area name contributed by this scope, joined to any enclosing one.
+     * An empty name contributes nothing, which is what makes a conditionally
+     * scoped component legal without a second code path.
+     */
+    name: string;
+    children: ReactNode;
+}
+/**
+ * Declare the area every `data-qa-id` beneath this point belongs to.
+ *
+ * It renders no element of its own — it is a context provider and nothing else,
+ * so dropping one into a layout can never change the DOM a test is driving.
+ */
+export declare const QaScope: ({ name, children }: QaScopeProps) => import("react").FunctionComponentElement<import("react").ProviderProps<string | undefined>>;
+/**
+ * The prefix in effect at this point in the tree, or `undefined` outside every
+ * scope. Exposed for the case a component needs the id string itself — a test
+ * hook that reports which element it will drive, for instance — rather than the
+ * attribute bag.
+ */
+export declare const useQaScope: () => string | undefined;
+/**
+ * Build the `data-qa-*` attribute bag for an element, with the enclosing scope's
+ * area already applied to its id.
+ *
+ * Outside any scope it is exactly `qaAttr`, so a component is free to use it
+ * before anyone has decided whether the feature around it gets a scope.
+ */
+export declare const useQaAttr: (options: QaAttrOptions) => QaAttributes;

package/dist/react/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The React half of the contract. It binds `src/core`'s attribute helper to a
+ * scope that travels down the tree; it adds no attribute family of its own.
+ */
+export { QaScope, useQaScope, useQaAttr } from './QaScope.js';
+export type { QaScopeProps } from './QaScope.js';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@firu-daniel/agent-qa-attrs",
+  "version": "0.1.0",
+  "description": "A data-qa-* attribute contract that makes a React app deterministically drivable by browser-driving agents and end-to-end tests.",
+  "license": "MIT",
+  "author": "firu-daniel",
+  "homepage": "https://github.com/firu-daniel/straightedge/tree/main/packages/agent-qa-attrs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firu-daniel/straightedge.git",
+    "directory": "packages/agent-qa-attrs"
+  },
+  "keywords": [
+    "testing",
+    "e2e",
+    "playwright",
+    "data-qa",
+    "react",
+    "agents",
+    "test-attributes"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup && npm run build:types",
+    "clean": "rm -rf dist",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --outDir dist"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}