feat: decouple selectors from root seelctors

[sergeyshmakov]

Summary by cubic

Decoupled child selector decorators from root selectors so classes without @RootSelector resolve from page or a fragment’s locator. Expanded helper APIs and updated docs/skill; switched lists to @ListSelector with prefixed data-testid values and added a raw Locator list accessor.

• New Features
  • Child selector resolution order: LOCATOR_SYMBOL → this.locator (fragment) → page.locator("body"); locator wins over page; throws if none found.
  • Plain host support: classes with only page can use @Selector*; fixtures accept page-only hosts; added example tests for raw list locators.
  • Fragment support: classes with readonly locator host nested @Selector* under this.locator.
  • Lists: use @ListSelector("CartItem_") with data-testid="CartItem_${id}"; added raw Locator accessor (CartItemRows).
  • API additions: PageObject gains waitPropAbsence() and expect({ message }); ListPageObject adds getAll(), last(), filterByTestId(), getItemByIdMask().
  • Docs/Skill: README and skills/playwright-page-object/SKILL.md updated to cover page-only hosts, fragments, and adoption path; requirements set to Node >=20, @playwright/test >=1.35.0, and TypeScript >=5.0.

^{Written for commit 1463ecf. Summary will update on new commits.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ca33bc547e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

2 issues found across 13 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/decorators/selectorBy.ts">

<violation number="1" location="src/decorators/selectorBy.ts:5">
P2: Exact duplicate of `isLocatorLike` from `rootSelectors.ts`. Consider extracting it into `../protocol` (or a shared internal module) so a future change to the duck-type check doesn't need to be synchronized across two files.</violation>

<violation number="2" location="src/decorators/selectorBy.ts:24">
P1: Reading `instance.locator` here can trigger a `@Selector*`-decorated accessor of the same name, which re-enters `resolveLocator()` → `tryHostLocatorRoot()` → `instance.locator` → infinite recursion (stack overflow). Use property-descriptor inspection (e.g., `Object.getOwnPropertyDescriptor` walking the prototype chain) to detect a plain data/value property without invoking getters, and skip or fall through when the property is an accessor (getter).</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

🎉 This PR is included in version 1.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀