@pomeranian/lib-essential
Status: implemented Unreleased general interactions, reusable action capabilities and foundational controls, locally buildable and packable. No npm publication exists.
Element<Root> extends core DomPageObject<Root> and inherits its exact factories, grouping, application roots and explicit target/defaultTarget authoring. Constructors are technically public for class-factory composition; direct new remains unsupported. Its delivered general actions are click, dblclick, hover, focus, blur, press, pressSequentially, native-deprecated type and selectText.
Control actions have complete native contracts: parameters, options, results, applicability, waits and errors are preserved through the live .locator. selectOption returns Promise<string[]>; routine tests may ignore the result. These are complete actions; deliberate raw observations remain on .locator.
import { DomPageObject, PageObject, rootFixture } from "@pomeranian/core";
import { Element, TextInput, TextArea, Checkbox, Select } from "@pomeranian/lib-essential";
class Menu extends PageObject<App> {
Continue = Element.create(this, "button");
}
class App extends DomPageObject<App> {
override defaultTarget = "main";
Menu = Menu.create(this);
}
const appTest = test.extend<{ app: App }>({ app: rootFixture(App) });
appTest("essential actions use the application scope", async ({ page, app }) => {
await page.setContent(
"<main><button onclick=\"this.textContent='Done'\">Continue</button></main>",
);
await app.Menu.Continue.click();
await expect(app.Menu.Continue.locator).toHaveText("Done");
});Delivered owners
| Action | Defining capability | Foundational controls |
|---|---|---|
fill | Fillable | Inherited through EditableValue by TextInput, TextArea, ContentEditable |
clear | EditableValue (builds on Fillable) | TextInput, TextArea, ContentEditable |
appendText | EditableText (builds on EditableValue) | TextInput, TextArea |
check | Checkable | Radio; inherited through CheckableUncheckable by Checkbox |
uncheck, setChecked | CheckableUncheckable (builds on Checkable) | Checkbox |
selectOption | SelectableOptions | Select |
click, dblclick, hover, focus, blur, press, pressSequentially, type, selectText | Element | Inherited by all six controls |
Each operation has one implementation inherited through the bundle hierarchy. TextInput and TextArea are siblings. Radio has no uncheck or setChecked; ContentEditable has fill/clear without appendText. There is no toggle helper. Assertion capabilities remain independently composable under decision #28, without an implemented assertion API in this slice.
Migration from universal Element actions
Changed in @pomeranian/lib-essential@Unreleased: fill, clear, check, uncheck, setChecked and selectOption move off Element with no compatibility forwarding. The initial form delivery (#35) remains accepted history. selectText stays on Element; native type deprecation is separate from this ownership change. Use TextInput.fill for replacement or inherited pressSequentially for keyboard input.
Previously Element.create(page, "input").fill("Ada") supplied the form action. Now select an appropriate control explicitly:
class Form extends DomPageObject {
override defaultTarget = "form";
Name = TextInput.create(this, "input[type=text]");
Agree = Checkbox.create(this, "input[type=checkbox]");
Choice = Select.create(this, "select");
}
test("complete form actions need no raw reads", async ({ page }) => {
await page.setContent(
"<form><input type=text><input type=checkbox><select><option value=a>A</option><option value=b>B</option></select></form>",
);
const form = Form.create(page);
await form.Name.fill("Ada");
await form.Name.selectText();
await form.Name.clear();
await form.Name.fill("Grace");
await form.Name.selectText();
await form.Name.appendText(" Hopper");
await form.Agree.check();
await form.Agree.uncheck();
await form.Agree.setChecked(true);
await form.Choice.selectOption("b");
await expect(form.Name.locator).toHaveValue("Grace Hopper");
await expect(form.Agree.locator).toBeChecked();
await expect(form.Choice.locator).toHaveValue("b");
});Alternatively, give a named custom component only the capabilities it needs. A capability requires a public locator: Locator, so it can compose above core DomPageObject or a custom DOM component without inheriting Element. It does not inspect or discover the target type:
import { EditableText } from "@pomeranian/lib-essential/editable-text";
import { checkLibrary, defaultInstanceType, type UnboundRoot } from "@pomeranian/core/authoring";
class CustomComponent extends DomPageObject {
componentName = "Search";
}
class EditableComponent extends CustomComponent.with(EditableText) {
override defaultTarget = "input";
}
class LibraryField<
Root extends UnboundRoot = UnboundRoot,
Value = string,
Extra = boolean,
> extends Element.with(EditableText)<Root> {
declare readonly [defaultInstanceType]: {
instance: LibraryField;
parameters: { root: Root; value: Value; extra: Extra };
};
override get root(): Root {
return super.root;
}
override defaultTarget = "input";
#value: Value | undefined = undefined;
#extra: Extra | undefined = undefined;
value(): Value | undefined {
return this.#value;
}
extra(): Extra | undefined {
return this.#extra;
}
}
checkLibrary<LibraryField>()(LibraryField);
class BoundField extends LibraryField<App, number, Date> {}All six controls require explicit targets unless an application subclass declares defaultTarget. Names express intended subjects rather than eagerly proving DOM type. Native fill can act on supported structured inputs, labels retarget only for native-supported operations, and readonly/disabled/missing state retains native waiting. A control's .locator still identifies its original target, including a label. DOM replacements and type changes are evaluated when each action runs. Explicitly applying CheckableUncheckable to a radio does not make native unchecking valid.
Appending native text
Added in @pomeranian/lib-essential@Unreleased: EditableText composes EditableValue (and therefore Fillable) and owns appendText(text, options?): Promise<void>. TextInput and TextArea now compose this bundle as siblings. Existing fill/clear calls retain their native behavior. Custom components that need append should select EditableText once instead of stacking it with either ancestor bundle.
Append reads the current native value internally, concatenates the suffix at the end regardless of selection or caret, and calls native fill with the supplied options. It retains fill's native constraints, waiting and errors; it does not promise per-character keyboard events. The read and fill are not atomic against concurrent application changes: an edit or target replacement between them can change or overwrite the result. The operation does not retry the whole read/append/fill mutation.
Native fill options include force, timeout, signal and deprecated noWaitAfter (which has no effect at the supported pin). The timeout applies to each stage independently, rather than imposing a single total budget. The signal cancels either stage; force affects native fill's actionability checks and does not bypass append's supported-target check.
The live target must be a native text/search/email/password/tel/url input (including implicit or invalid types resolving to text) or textarea. Structured controls such as number/date, contenteditable, labels and other elements are explicitly rejected for append. Inherited native fill/clear keep their own broader applicability, including native label retargeting; append does not discover a label's associated control. .locator and explicit targets/defaultTarget retain their original meaning. Check happens at action time, so a class name does not cache or guarantee a DOM type.
The checked form example above appends a surname after selection without replacing the existing name. Standalone textarea and application-bound subclass examples use the same implementation:
class Search extends TextInput<App> {
override defaultTarget = "input[type=search]";
}
test("standalone and app-bound controls append native text", async ({ page }) => {
await page.setContent("<main><input type=search value=Hello><textarea>First</textarea></main>");
const notes = TextArea.create(page, "textarea");
await notes.appendText("\nSecond", { timeout: 1000 });
await expect(notes.locator).toHaveValue("First\nSecond");
await rootFixture(App)({ page }, async (app) => {
const search = Search.create(app);
await search.selectText();
await search.appendText(" world");
await expect(search.locator).toHaveValue("Hello world");
expect(search.root).toBe(app);
});
});For a custom base or generic library wrapper, the checked authoring example above selects EditableText. Preserve fresh defaultInstanceType metadata for root/default/extra parameters and the forwarding root getter when needed. Future SearchInput, TelephoneInput, UrlInput, EmailInput and PasswordInput classes in #45 inherit this behavior through TextInput. ContentEditable deliberately remains on EditableValue; rich-editor formatting preservation belongs to #41.
Composition safety and customization
Use the broadest required bundle once: EditableText already includes EditableValue and Fillable, EditableValue includes Fillable, and CheckableUncheckable already includes Checkable. Stacking overlapping bundles creates redundant contributions and can cause member collisions. Ordinary JavaScript precedence applies; composition performs no runtime collision check. Compatible override methods can explicitly call super, but do not automatically combine competing implementations.
Capabilities can contribute children and shared behavior. Compatible child overrides customize the final child read through this; inherited initializers still run, and previously captured children retain their original identity and side effects. See the checked child customization examples. Reusable generic composed wrappers declare fresh metadata for all independent parameters and, where required, a forwarding root getter as shown above. Concrete descendants inherit those contracts.
Strict compiler proofs cover tested factory/default/root/generic contracts and reject grouping bases lacking a Locator. They do not validate original member kinds or every unsafe source form. The optional checker (#25) is pending; a checked safety claim requires its source checks together with strict compiler checks when delivered. Ordinary consumers retain unchecked JavaScript behavior and generic-intersection limitations. Runtime imports require neither the checker nor a compiler.
Package entry points and remaining work
Every delivered class and factory is exported from @pomeranian/lib-essential and its explicit kebab-case defining module, for example /text-input, /text-area, /content-editable, /fillable, /editable-value, /editable-text, /checkable, /checkable-uncheckable and /selectable-options. /element, /checkbox, /radio and /select complete the inventory. Root/direct ESM and CommonJS exports share the same runtime identities. Included sources, declarations and maps support debugging; source/dist implementation paths are not public imports.
Build core and essential before packing; installed consumers use both tarballs with aligned consumer-supplied playwright-core and runner or standalone playwright peers. The verified minimum/current Playwright pins coincide at 1.64.1; TypeScript consumer checks cover 6.0.3 and 7.0.2. No automatic selectors or npm publication are introduced.
Remaining native input flavors (#45) and general/file interactions (#36) remain pending. No setInputFiles, dragTo, dispatchEvent, tap or scrollIntoViewIfNeeded wrapper is delivered here. See the complete essential action contract.
Available since @pomeranian/lib-essential@Unreleased.
Inherited construction and target APIs: Available since @pomeranian/core@Unreleased.