@ingcreators/annot-product-docs 0.1.0 → 0.3.0

package/dist/fixture.d.ts

@@ -0,0 +1,111 @@
+import { Locator, Page } from '@playwright/test';
+import { OverlaySpec } from './types.js';
+export interface ProductDocsSyncOptions {
+    /** Must match a `<Screen id="...">` JSX block in the MDX file. */
+    id: string;
+    /** Absolute or cwd-relative path to the `.mdx` file. */
+    mdxPath: string;
+    /**
+     * Override the locator used as the snapshot root. Defaults to
+     * the page's `body` element. Useful when the test is scoped to
+     * a specific dialog or section.
+     */
+    rootLocator?: Locator;
+    /**
+     * Override the HTML attribute whitelist for `annot:attributes`
+     * collection. Default is `DEFAULT_ATTR_WHITELIST` — covers the
+     * common form-control + accessibility attrs.
+     */
+    attributeWhitelist?: readonly string[];
+}
+/**
+ * @deprecated Renamed to {@link ProductDocsSyncOptions} in Phase 3
+ * of `docs/plans/playwright-screenshot-fixture-relayer.md` for
+ * naming clarity (the helper synchronizes the MDX comment blocks
+ * with the live UI — it does not take a screenshot). The old name
+ * keeps working but new code should use `ProductDocsSyncOptions`.
+ */
+export type ScreenCaptureOptions = ProductDocsSyncOptions;
+export interface ProductDocs {
+    sync(opts: ProductDocsSyncOptions): Promise<void>;
+}
+/**
+ * @deprecated Renamed to {@link ProductDocs} in Phase 3 of
+ * `docs/plans/playwright-screenshot-fixture-relayer.md`. The old
+ * `Screen` name is ambiguous (collides with `@testing-library/react`'s
+ * `screen` + reads like a Playwright built-in). New code should
+ * use `ProductDocs`.
+ */
+export type Screen = ProductDocs;
+/**
+ * HTML attributes captured into the `annot:attributes` block by
+ * default. Focused on form-control + accessibility shape — the
+ * stuff a screen-specifications spreadsheet / operation manual cares about per element.
+ *
+ * Hosts can override per-call via `opts.attributeWhitelist`.
+ */
+export declare const DEFAULT_ATTR_WHITELIST: readonly string[];
+/**
+ * `test = annotatorTest.extend({ productDocs })` — drop-in for
+ * `@playwright/test`'s `test` plus a `productDocs` fixture for
+ * the docs flow. Tour files (`tests/docs/*.spec.ts`) import this
+ * `test` instead of `@playwright/test`:
+ *
+ * ```ts
+ * import { test } from "@ingcreators/annot-product-docs";
+ *
+ * test("login flow", async ({ page, productDocs }) => {
+ *   await page.goto("/login");
+ *   await productDocs.sync({
+ *     id: "login",
+ *     mdxPath: "docs/books/screen-spec/screens/SC-001-login.mdx",
+ *   });
+ * });
+ * ```
+ *
+ * For back-compat the same fixture is also exposed as `screen`
+ * with a `.capture()` method (deprecated since Phase 3 of the
+ * relayer plan; remove after the documented deprecation window).
+ */
+export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
+    annotator: import('@ingcreators/annot-playwright').PlaywrightAnnotator;
+} & {
+    productDocs: ProductDocs;
+    screen: ProductDocs;
+}, import('@playwright/test').PlaywrightWorkerArgs & import('@playwright/test').PlaywrightWorkerOptions>;
+/**
+ * Standalone sync helper — same behaviour as
+ * `productDocs.sync(...)` but takes the `Page` directly.
+ * Exported so callers who build their own Playwright fixture
+ * (e.g. composing additional fixtures on top) can still drive
+ * the docs-sync flow.
+ *
+ * Idempotent: if `mdxPath` already has `annot:snapshot` /
+ * `annot:attributes` blocks, they're replaced in place; if not,
+ * they're appended. Files without `annot:` frontmatter throw —
+ * the fixture refuses to touch non-annot MDX.
+ */
+export declare function syncProductDocs(page: Page, opts: ProductDocsSyncOptions): Promise<void>;
+/**
+ * @deprecated Renamed to {@link syncProductDocs} in Phase 3 of
+ * `docs/plans/playwright-screenshot-fixture-relayer.md`. The old
+ * name reads as if a screenshot is captured; the function
+ * actually synchronizes MDX comment blocks. The deprecated alias
+ * is a reference-equality re-export of the new implementation so
+ * `===` checks across the rename boundary keep working.
+ */
+export declare const captureScreen: typeof syncProductDocs;
+/**
+ * Walk the overlays in a `<Screen>`, resolve each one's `match`
+ * against the live page, and emit a YAML block of the form:
+ *
+ *   role "Name":
+ *     attrA: value
+ *     attrB: value
+ *
+ * Only overlays whose `match` resolves to exactly one element
+ * contribute a section. Overlays with zero hits or multiple
+ * hits are skipped (the drift detector in Phase 1 PR 4 raises
+ * those — duplicating the diagnostic here would be noisy).
+ */
+export declare function collectAttributesYaml(page: Page, overlays: OverlaySpec[], whitelist: readonly string[]): Promise<string>;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { filterAnnotMdxFiles, main, walkMdx, } from './cli.js';
+export { annotDocsConfigSchema, annotFrontmatterSchema, defineConfig, isScreenRole, } from './config.js';
+export type { DetectDriftOptions, DriftFinding, DriftKind, DriftSeverity, } from './drift.js';
+export { detectDrift, detectDriftFromYaml, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
+export type { ProductDocs, ProductDocsSyncOptions, Screen, ScreenCaptureOptions, } from './fixture.js';
+export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, syncProductDocs, test, } from './fixture.js';
+export type { ParseMdxOptions } from './mdx.js';
+export { parseMdx, parseMdxFile, updateCommentBlocks } from './mdx.js';
+export type { BoxedEntry } from './mdx-annotations.js';
+export { buildBadgeAnnotations, emptyAnnotationsSvg, parseSnapshotBoxes, resolveMdxAnnotations, svgFromBadges, svgFromBboxAnnotations, } from './mdx-annotations.js';
+export type { ResolveFailureKind, ResolveResult, SnapshotEntry, } from './resolver.js';
+export { parseSnapshot, resolveMatch, resolveOverlays, } from './resolver.js';
+export type { AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
+export type { AnnotDocsConfig, BookConfig } from './types-config.js';