USWDS-proposals: Add directory for pre-alpha web components #18

amyleadem · 2024-11-26T15:52:43Z

Summary

Create a README and template for the web component pre-alphas.

Note

The pre-alpha requirements are documented in the Web Components release lifecycle doc (Google docs 🔒)

Preview links

Testing and review

Confirm that the location for this directory makes sense
Confirm that the name for this directory makes sense
Confirm the template is comprehensive and will capture the decisions we need to make during this phase
Confirm the format is intuitive and follows a logical order
Confirm the README addresses necessary topics and is free from error

web-components/README.md

adding links and naming

annepetersen

With the edits I made, looks good to me. But check my work too, y'all. 😅

mahoneycm

A couple potential suggestions and questions! Nothing blocking.

mahoneycm · 2024-11-26T23:00:58Z

web-components/README.md

Question: Does the rest of the proposals file structure make sense with this change? Should we create a core dir as well?

This is a good note. The repo was originally designed to just be for component proposals, and I think the recent repo growth is showing strangely in both the file structure and base README. Now that the repo will also include ADRs and Elements pre-alphas, we should at least address that in the README and consider if the file structure still makes sense. I've opened #19 to address the README piece of this.

mahoneycm · 2024-11-26T23:02:06Z

web-components/README.md

+
+## How to create a pre-alpha document
+
+1. Create a branch for the web component pre-alpha using the following naming structure: `[component-name]-pre-alpha`


Question: Should we prefix the PRs with our initials?

Suggested change

1. Create a branch for the web component pre-alpha using the following naming structure: `[component-name]-pre-alpha`

1. Create a branch for the web component pre-alpha using the following naming structure: `[initials]-[component-name]-pre-alpha`

That's a good point @mahoneycm. Do you see any issues with not having initials?

We do this with code to avoid collision in branch names when we're working on the same feature.

It's doubtful that two of us would be working on the same pre-alpha document. Although it can happen if we want to make significant changes via a PR.

I updated the recommended branch structure to [contributor initials]-pre-alpha-[component-name] in 2e1e23f.

Let me know if you have any objections or concerns.

mahoneycm · 2024-11-26T23:07:07Z

web-components/_template.md

+  You can find these files in Google Drive:
+  https://drive.google.com/drive/folders/1F8z7v5RCOV3D33iEz7TR0B8IHv20WNMF


Question: Should we make a note that this link is internal only?

I know we have the note that only the core team can make the proposals for now but I'm curious if we should make note in case anyone is poking around the files.

Might not be important!

I added a "limited access" note in 5020a85.

web-components/_template.md

mahoneycm · 2024-11-26T23:08:53Z

web-components/_template.md

+
+<!--
+| USWDS 3 variant | Web components variant | Description | Defined via |
+|--------|--------|--------|--------|
+|  |  |  |  |
+-->


Question: Not sure I follow what the the Web components variant is supposed to be listed as here.

Is this just the name of the variant? Would this differ from the USWDS 3 variant?

web-components/_template.md

mejiaj

Thanks for creating this @amyleadem. Overall it looks good. Left a few comments, but nothing is blocking.

I've also made some formatting changes using the built-in markdown formatter in Prettier.

mejiaj · 2024-11-26T21:36:16Z

web-components/README.md

+
+## How to create a pre-alpha document
+
+1. Create a branch for the web component pre-alpha using the following naming structure: `[component-name]-pre-alpha`


thought: Flipping this could cleanly separate the pre-alpha branches listed from others.

- usa-modal-pre-alpha - usa-accordion-pre-alpha - usa-text-input-pre-alpha + pre-alpha-usa-modal + pre-alpha-usa-accordion + pre-alpha-usa-text-input

Alternatively, we could even take an approach like the web components repo and do something like:

pre-alpha/usa-accordion

I updated the recommended branch structure to [contributor initials]-pre-alpha-[component-name] in 2e1e23f.

Let me know if you have any objections or concerns.

mejiaj · 2024-11-26T21:52:00Z

web-components/_template.md

+_Provide a link to the code samples from the landscape analysis._
+
+<!--
+  You can find these files in Google Drive:
+  https://drive.google.com/drive/folders/1F8z7v5RCOV3D33iEz7TR0B8IHv20WNMF
+-->
+
+[Component] code samples from the landscape analysis (Google docs :lock:)


question: Confirming, we're only linking to the code samples and not the landscape analysis spreadsheet?

Yes, I don't think we need to do a full analysis of each components. It feels more appropriate to just grab code samples for comparison.

mejiaj · 2024-11-26T22:01:46Z

web-components/_template.md

+#### Current variants
+
+<!--
+| USWDS 3 variant | Web components variant | Description | Defined via |


question: What does Defined via mean? What are the options?

It was intended to capture how the user would set this variant in the light DOM.

Since I imagine this would almost always be a prop of some sort, I updated the heading to "Related prop" in 5020a85.

Let me know if that is still unclear.

mejiaj · 2024-12-03T15:09:11Z

web-components/README.md

+
+## How to create a pre-alpha document
+
+1. Create a branch for the web component pre-alpha using the following naming structure: `[component-name]-pre-alpha`


That's a good point @mahoneycm. Do you see any issues with not having initials?

We do this with code to avoid collision in branch names when we're working on the same feature.

It's doubtful that two of us would be working on the same pre-alpha document. Although it can happen if we want to make significant changes via a PR.

mejiaj · 2024-12-03T15:43:00Z

web-components/_template.md

+
+### Critical content
+
+_In a table, list the component content that is critical for user understanding. These elements should always be painted on the page, even when JavaScript is unavailable or slow._


polish: Small suggestion to remove the word painted because it might be too technical.

Suggested change

_In a table, list the component content that is critical for user understanding. These elements should always be painted on the page, even when JavaScript is unavailable or slow._

_In a table, list the component content that is critical for user understanding. These elements should always be on the page, even when JavaScript is unavailable or slow._

Updated in 5020a85

mejiaj · 2024-12-03T15:49:41Z

web-components/_template.md

+
+### Light DOM
+
+_Provide a code sample for the web component in the light DOM. Provide default and complex implementations when applicable._


polish: The heading already mentions light DOM. We can use plain language for the requirements.

Suggested change

_Provide a code sample for the web component in the light DOM. Provide default and complex implementations when applicable._

_Provide an example for how the web component would be used. Include a default example and complex example (when applicable)._

Updated the copy to "Provide a code sample of how a user would add this web component to their project. Provide a default example and a complex example (when applicable)." in 5020a85

mejiaj · 2024-12-03T15:53:21Z

web-components/_template.md

+_Provide a code sample of how the component will be built in the shadow DOM. Provide default and complex implementations when applicable._
+
+<!--
+```html


polish: We could add clarity by adding an HTML comment marking that this is the shadow DOM markup.

Suggested change

```html

```html

Good idea. Added in 5020a85

amyleadem and others added 4 commits November 26, 2024 08:43

Add web-components directory

b794b73

Remove text-input.md

8fe26c5

Update README.md

aaf522c

Update README.md

80526ac

amyleadem commented Nov 26, 2024

View reviewed changes

web-components/README.md Outdated Show resolved Hide resolved

amyleadem marked this pull request as ready for review November 26, 2024 20:44

amyleadem requested a review from a team as a code owner November 26, 2024 20:44

amyleadem requested review from heymatthenry, mejiaj, annepetersen, thisisdano and mahoneycm November 26, 2024 20:44

Update README.md

20b6a83

adding links and naming

annepetersen previously approved these changes Nov 26, 2024

View reviewed changes

Formatting fixes to README

a78c9db

mejiaj dismissed annepetersen’s stale review via a78c9db November 26, 2024 21:18

Formatting fixes to web components template

38bd796

mahoneycm reviewed Nov 26, 2024

View reviewed changes

Format tables (automagically)

3911ae9

mejiaj reviewed Dec 3, 2024

View reviewed changes

amyleadem added 2 commits December 10, 2024 09:17

Update branch name structure

2e1e23f

Update copy in template.md

5020a85

amyleadem requested review from mahoneycm, mejiaj and annepetersen December 10, 2024 17:12

amyleadem changed the title ~~USWDS-proposals: Add web-components directory~~ USWDS-proposals: Add directory for pre-alpha web components Dec 10, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS-proposals: Add directory for pre-alpha web components #18

USWDS-proposals: Add directory for pre-alpha web components #18

amyleadem commented Nov 26, 2024 •

edited

Loading

annepetersen left a comment

mahoneycm left a comment

mahoneycm Nov 26, 2024

amyleadem Nov 27, 2024

mahoneycm Nov 26, 2024

mejiaj Dec 3, 2024

amyleadem Dec 10, 2024

mahoneycm Nov 26, 2024

amyleadem Dec 10, 2024

mahoneycm Nov 26, 2024

mejiaj left a comment

mejiaj Nov 26, 2024

amyleadem Dec 10, 2024

mejiaj Nov 26, 2024

amyleadem Dec 10, 2024

mejiaj Nov 26, 2024

amyleadem Dec 10, 2024

mejiaj Dec 3, 2024

mejiaj Dec 3, 2024

amyleadem Dec 10, 2024

mejiaj Dec 3, 2024

amyleadem Dec 10, 2024

mejiaj Dec 3, 2024

amyleadem Dec 10, 2024


		## How to create a pre-alpha document

		1. Create a branch for the web component pre-alpha using the following naming structure: `[component-name]-pre-alpha`

		You can find these files in Google Drive:
		https://drive.google.com/drive/folders/1F8z7v5RCOV3D33iEz7TR0B8IHv20WNMF


		### Critical content

		_In a table, list the component content that is critical for user understanding. These elements should always be painted on the page, even when JavaScript is unavailable or slow._


		### Light DOM

		_Provide a code sample for the web component in the light DOM. Provide default and complex implementations when applicable._

	_Provide a code sample for the web component in the light DOM. Provide default and complex implementations when applicable._
	_Provide an example for how the web component would be used. Include a default example and complex example (when applicable)._

-```html
+```html
+<!-- #shadow-root -->

USWDS-proposals: Add directory for pre-alpha web components #18

Are you sure you want to change the base?

USWDS-proposals: Add directory for pre-alpha web components #18

Conversation

amyleadem commented Nov 26, 2024 • edited Loading

Summary

Preview links

Testing and review

annepetersen left a comment

Choose a reason for hiding this comment

mahoneycm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mejiaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem commented Nov 26, 2024 •

edited

Loading