{"id":51340008,"url":"https://github.com/appium/css-locator-to-native","last_synced_at":"2026-07-02T06:33:17.400Z","repository":{"id":363177067,"uuid":"1262151990","full_name":"appium/css-locator-to-native","owner":"appium","description":"Platform-agnostic CSS selector parsing and normalization for native locator transformation","archived":false,"fork":false,"pushed_at":"2026-06-07T18:52:02.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T20:12:26.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appium.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"open_collective":"appium"}},"created_at":"2026-06-07T16:33:22.000Z","updated_at":"2026-06-07T18:52:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/appium/css-locator-to-native","commit_stats":null,"previous_names":["appium/css-locator-to-native"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/appium/css-locator-to-native","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fcss-locator-to-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fcss-locator-to-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fcss-locator-to-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fcss-locator-to-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appium","download_url":"https://codeload.github.com/appium/css-locator-to-native/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fcss-locator-to-native/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35036553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-02T06:33:16.473Z","updated_at":"2026-07-02T06:33:17.385Z","avatar_url":"https://github.com/appium.png","language":"TypeScript","funding_links":["https://opencollective.com/appium"],"categories":[],"sub_categories":[],"readme":"# @appium/css-locator-to-native\n\nPlatform-agnostic CSS selector parsing and normalization for native locator transformation.\n\n## Installation\n\n```bash\nnpm install @appium/css-locator-to-native\n```\n\n## Quick start\n\n```typescript\nimport {\n  createCssTransformer,\n  type AttributeSchema,\n  type ParsedSelector,\n  type StrategyKey,\n} from '@appium/css-locator-to-native';\n\nconst schema: AttributeSchema = {\n  attributes: {\n    visible: {type: 'boolean'},\n    name: {type: 'string', aliases: ['id']},\n    index: {type: 'numeric', aliases: ['nth-child']},\n  },\n  booleanFormat: 'zero-one',\n};\n\nconst emitters = {\n  native: {\n    strategy: 'my-native-strategy',\n    emit(parsed: ParsedSelector) {\n      // Map ParsedSelector IR to your platform's selector syntax\n      return parsed.rule.tag ?? '*';\n    },\n  },\n};\n\nconst transformCss = createCssTransformer({\n  schema,\n  emitters,\n  resolveStrategy(): StrategyKey\u003ctypeof emitters\u003e {\n    return 'native';\n  },\n});\n\nconst {strategy, selector} = transformCss('window#foo[visible]');\n// =\u003e { strategy: 'my-native-strategy', selector: '...' }\n```\n\n## API\n\nEverything is exported from a single entry point:\n\n| Export | Description |\n|---|---|\n| `normalizeCssSelector(css, schema)` | Parse and normalize a CSS selector into a `ParsedSelector` IR |\n| `createCssTransformer(config)` | Returns a function that parses CSS and produces a `NativeLocator` |\n| `InvalidSelectorError` | CSS syntax cannot be parsed |\n| `UnsupportedSelectorError` | Parsed CSS uses unsupported features or unknown attributes |\n| `UnresolvedStrategyError` | No matching emitter for the resolved strategy key |\n\n### ParsedSelector IR\n\nNormalization produces a platform-agnostic intermediate representation. The IR captures CSS structure — tags, classes, `#id`, attributes, pseudos, combinators — validated against your schema. It does **not** encode iOS class chain, UiAutomator, or any other native syntax.\n\n```typescript\ninterface ParsedSelector {\n  rule: ParsedRule; // first comma-separated rule only\n}\n\ninterface ParsedRule {\n  combinator?: 'descendant' | 'child';\n  tag?: string;           // raw CSS tag (may be '*')\n  classes: string[];      // raw class tokens\n  id?: string;            // raw #id value\n  attributes: ParsedAttribute[];\n  pseudos: ParsedAttribute[];\n  nested?: ParsedRule;\n}\n```\n\n### Attribute schemas\n\nDrivers declare which CSS attributes are valid and how booleans are coerced:\n\n```typescript\ninterface AttributeSchema {\n  attributes: Record\u003cstring, {type: 'boolean' | 'string' | 'numeric'; aliases?: string[]}\u003e;\n  booleanFormat?: 'zero-one' | 'true-false' | 'literal';\n}\n```\n\n- **`zero-one`** — `true`/`1`/empty → `'1'`, `false`/`0` → `'0'`\n- **`true-false`** — `true`/empty → `'true'`, `false` → `'false'`\n- **`literal`** (default) — keep the raw attribute value unchanged; implicit booleans (no value) stay unset\n\nTag, class, and `#id` mapping (e.g. `XCUIElementType*` prefixing, `resourceId` prefixing) is entirely the driver's responsibility in emitters.\n\n### Multi-strategy routing\n\n`createCssTransformer` requires a registry of `StrategyEmitter`s and a `resolveStrategy` callback. The resolver picks which emitter to use based on selector shape; the transformer returns both the target strategy name and the native selector string.\n\n```typescript\ninterface NativeLocator {\n  strategy: string;\n  selector: string;\n}\n```\n\nA driver with a single target strategy uses a one-entry registry and a trivial resolver.\n\n## Driver integration pattern\n\nPlatform logic stays in the driver. A typical layout:\n\n```\nlib/css/\n  schema.ts          # AttributeSchema for the platform\n  *-emitter.ts       # StrategyEmitter implementations\n  resolve-helpers.ts # isSimpleIdSelector, etc.\n  index.ts           # createCssTransformer wrapper\n```\n\nIn `find` commands, use the strategy from the transform result instead of hardcoding it:\n\n```typescript\nif (strategy === 'css selector') {\n  ({strategy, selector} = cssToNativeLocator(selector));\n}\n```\n\n## Supported CSS subset\n\nMatches the subset accepted by existing Appium drivers:\n\n- Tags (including `*`), `#id`, classes, attribute selectors (`=`, `*=`, `^=`, `$=`, `~=`)\n- Child (`\u003e`) and descendant (space) combinators\n- Pseudo-classes accepted as attributes per schema (e.g. `:visible`, `:nth-child(2)`)\n- First comma-separated rule only (additional rules are ignored)\n- Unsupported: `+` / `~` combinators, pseudo-elements, nesting (`\u0026`), namespaces\n\n## Development\n\n```bash\nnpm install --no-package-lock\nnpm run typecheck   # type-check lib + test\nnpm run build       # compile to build/\nnpm test            # unit tests (compiled ESM)\nnpm run lint\nnpm run format:check\n```\n\n## Requirements\n\n- Node.js `^20.19.0 || ^22.12.0 || \u003e=24.0.0`\n- npm `\u003e=10`\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappium%2Fcss-locator-to-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappium%2Fcss-locator-to-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappium%2Fcss-locator-to-native/lists"}