lit / lit/lit.dev

Add filename caption to switchable-sample?

Open
#843 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
142
Forks
230
PR merge metrics
No merged PRs in 30d

Description

Currently, we have switchable samples, and we have the `` switch to supply different text content depending on the current state of the TS/JS switch. In some tutorials, we end up using them like this:

```
#### date-display.

{% switchable-sample %}
...
{% endswitchable-sample %}
```

There are a couple of potential issues with this:

1) Because it's not built into switchable sample, we need to enforce consistent formatting manually.
2) The content isn't semantic--this isn't really a header, it's a figure caption. Notably, anything after the sample should be considered separate, not part of a section titled "date-display.ts".
3) When I tested with a screen reader, it read "Heading: date-display," leaving off the ".ts" at the end (the part added by the `` element.

Semantically, it'd be nice to do something like this:

```
{% switchable-sample "date-display.%" %}
... etc.
```

And have that end up as:

```

date-display.ts

...

```

Or something. Perhaps using `date-display.tsdate-display.js` in the caption would make the full text readable by screen readers. That would be a pain to type, but easy to do with a macro.

Contributor guide

Open the contributing guide

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 by locating the switchable-sample entry point and existing usage in the tutorials. Review how the current heading-based filename captions are rendered, then determine the agreed caption API and semantic output. Done means switchable samples provide consistent figure captions whose complete TS/JS filenames are accessible to screen readers.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
accessibility, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.