projectwallace / projectwallace/css-analyzer

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.

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

Description

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.

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.

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.