Skip to content

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

@bartveneman

Description

@bartveneman

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions