Add value-level helpers to extract container names from `container`/`container-name` values and `@container` preludes

Open
#607 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
68/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
css, typescript
Domain
tooling

Research direction

Start in the values module exposed by @projectwallace/css-analyzer/values and inspect the parsed value and at-rule prelude shapes from parse_value and parse_atrule_prelude. Add the two proposed helpers so the listed declaration and @container examples produce the documented results, including none, type-only, and anonymous-query cases. Verify the examples and related analyzer checks.

Written by the indexing model from the issue text.

Description

✨ enhancement
Context

Tracking used and unused container names requires reading names from two places:
Declarationscontainer-name: sidebar and container: sidebar / inline-size
Usages@container sidebar (min-width: 400px)
Currently, consumers must manually parse both the declaration value and the at-rule prelude to extract these names. The logic for parsing container shorthand (splitting on / and reading the name portion) and for reading the leading name token from a @container prelude are both non-trivial enough to belong in the analyzer.

Proposed API
/**
 * Extract container names declared in a `container-name` value
 * or the name portion of a `container` shorthand value.
 * Returns an empty array if the value is `none` or contains only a type.
 */
function extractDeclaredContainerNames(
  parsed: ReturnType<typeof parse_value>
): string[]
/**
 * Extract the container name queried in a `@container` prelude, if any.
 * Returns null for anonymous container queries.
 */
function extractContainerQueryName(
  parsed: ReturnType<typeof parse_atrule_prelude>
): string | null

### Examples

```ts
import { parse_value } from '@projectwallace/css-parser/parse-value'
import { parse_atrule_prelude } from '@projectwallace/css-parser/parse-atrule-prelude'
import {
  extractDeclaredContainerNames,
  extractContainerQueryName,
} from '@projectwallace/css-analyzer/values'

extractDeclaredContainerNames(parse_value('sidebar'))
// → ['sidebar']

extractDeclaredContainerNames(parse_value('sidebar card'))
// → ['sidebar', 'card']

extractDeclaredContainerNames(parse_value('sidebar / inline-size'))
// → ['sidebar']

extractDeclaredContainerNames(parse_value('none'))
// → []

extractContainerQueryName(parse_atrule_prelude('container', 'sidebar (min-width: 400px)'))
// → 'sidebar'

extractContainerQueryName(parse_atrule_prelude('container', '(min-width: 400px)'))
// → null
Motiviation

Enables detection of undeclared container names (used in @container but never set via container-name) and unused container names (declared but never queried) without each consumer re-implementing container shorthand parsing.

Dominant language
TypeScript
Stars
366
Forks
15
Avg merge
3h 23m
Merged PRs (30d)
3

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from projectwallace/css-analyzer

All issues in projectwallace/css-analyzer

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.