Add README files for all JavaScript packages

app/javascript/packages/assets/README.md

@@ -0,0 +1,35 @@
+# `@18f/identity-assets`
+
+Utilities for resolving asset URLs from [Ruby on Rails' Asset Pipeline](https://guides.rubyonrails.org/asset_pipeline.html).
+
+## Usage
+
+Within your code, use `getAssetPath` and provide a raw asset path, where the expected return value is the URL resolved by the Ruby on Rails Asset pipeline:
+
+```ts
+const spriteURL = getAssetPath('sprite.svg');
+```
+
+The included Webpack plugin will scan for references to `getAssetPath` and add those as assets of the associated Webpack entrypoint.
+
+```ts
+// webpack.config.js
+
+module.exports = {
+  // ...
+  plugins: [
+    // ...
+    new RailsAssetsWebpackPlugin(),
+  ],
+};
+```
+
+The expectation is that this can be used in combination with a tool like [`WebpackManifestPlugin`](https://github.com/shellscape/webpack-manifest-plugin) to generate a JSON manifest of all assets expected to be loaded with a given Webpack entrypoint, so that the backend can ensure those asset paths are populated into a `<script type="applicaton/json" data-asset-map>` tag containing a JSON mapping of original asset names to the resolved URL.
+
+```html
+<script type="application/json" data-asset-map>
+  {
+    "sprite.svg": "https://cdn.example.com/path/to/sprite.svg"
+  }
+</script>
+```

app/javascript/packages/config/README.md

@@ -0,0 +1,21 @@
+# `@18f/identity-config`
+
+Utilities for retrieving global application configuration values.
+
+## Usage
+
+From your JavaScript code, retrieve a configuration value using the `getConfigValue` export:
+
+```ts
+const appName = getConfigValue('appName');
+```
+
+The configuration is expected to be bootstrapped in page markup within a `<script type="application/json" data-config>` script tag.
+
+```html
+<script type="application/json" data-config>
+  {
+    "appName": "Login.gov"
+  }
+</script>
+```

app/javascript/packages/device/README.md

@@ -0,0 +1,34 @@
+# `@18f/identity-device`
+
+Utilities for detecting details about the user's device.
+
+## Usage
+
+Import the desired utility function from the package:
+
+```ts
+import { isLikelyMobile } from '@18f/identity-device';
+
+isLikelyMobile();
+// true
+```
+
+## API
+
+### `isIPad`
+
+Returns true if the device is an iPad, or false otherwise.
+
+iPadOS devices no longer list the correct user agent. As a proxy, we check for the incorrect one (Macintosh) then test the number of touchpoints, which for iPads will be 5.
+
+### `isLikelyMobile`
+
+Returns true if the device is likely a mobile device, or false otherwise. This is a rough approximation, using device user agent sniffing.
+
+### `hasMediaAccess`
+
+Returns true if the current device allows access to camera device APIs.
+
+### `isCameraCapableMobile`
+
+Returns true if the current device is assumed to be a mobile device where a camera is available, or false otherwise. This is a rough approximation, using device user agent sniffing and availability of camera device APIs.

app/javascript/packages/document-capture-polling/README.md

@@ -0,0 +1,20 @@
+# `@18f/identity-document-capture-polling`
+
+Package implementing behaviors associated with the hybrid handoff document capture flow, where document capture is initiated on a desktop computer and completed on a mobile device. The behaviors of this package are responsible for polling for the result of a document capture happening on another device, and redirecting the user upon completion or failure.
+
+## Usage
+
+Initialize the package's binding with the polling endpoint and required elements:
+
+```ts
+import { DocumentCapturePolling } from '@18f/identity-document-capture-polling';
+
+new DocumentCapturePolling({
+  statusEndpoint: '/path/to/endpoint',
+  elements: {
+    backLink: document.querySelector('.link-sent-back-link'),
+    form: document.querySelector('.link-sent-continue-button-form'),
+  },
+}).bind();
+```
+

app/javascript/packages/document-capture/README.md

@@ -0,0 +1,22 @@
+# `@18f/identity-document-capture`
+
+React components for displaying a user interface for a user to upload or capture photos of their state-issued identification.
+
+## Usage
+
+Render the included `<DocumentCapture />` React component. Most settings are expected to be configured by wrapping the component with one or more of the included context provider components.
+
+```tsx
+import { render } from 'react-dom';
+import { DocumentCapture, AnalyticsContextProvider } from '@18f/identity-document-capture';
+
+const appRoot = document.getElementById('app-root');
+
+render(
+  <AnalyticsContextProvider trackEvent={/* ... */}>
+    {/* ... */}
+    <DocumentCapture />
+  </AnalyticsContextProvider>,
+  appRoot
+);
+```

app/javascript/packages/form-steps/README.md

@@ -0,0 +1,21 @@
+# `@18f/identity-form-steps`
+
+React components for managing a user's progression through a series of steps in a form.
+
+## Usage
+
+At a minimum, render the `<FormSteps />` React component with an array of step configurations. Each step must include a `name` and `form`, where the `form` is a React component that will be rendered once the user reaches the step.
+
+```tsx
+import { render } from 'react-dom';
+import { FormSteps } from '@18f/identity-form-steps';
+
+const STEPS = [
+  { name: 'First Step', form: () => <p>Welcome to the first step!</p> },
+  { name: 'Second Step', form: () => <p>Welcome to the second step!</p> },
+];
+
+const appRoot = document.getElementById('app-root');
+
+render(<FormSteps steps={STEPS} />, appRoot);
+```

app/javascript/packages/masked-text-toggle/README.md

@@ -0,0 +1,32 @@
+# `@18f/identity-masked-text-toggle`
+
+Package implementing behaviors associated with toggling the visibility of text which is masked by default due to its sensitivity.
+
+For example, a Social Security number may be masked to show only `6**-**-***4` by default, and allow a user to toggle the visibility of the full number if desired.
+
+## Usage
+
+Initialize the package's binding with the polling endpoint and required elements:
+
+```ts
+import MaskedTextToggle from '@18f/identity-masked-text-toggle';
+
+const toggle = document.querySelector('.masked-text-toggle');
+new MaskedTextToggle(toggle).bind();
+```
+
+The given toggle element is expected to be a checkbox, associated with the masked text wrapper by an `aria-controls` attribute.
+
+The masked text wrapper is expected to contain two variations of the text: a masked form (with a `data-masked="true"` attribute) and a revealed form (with a `data-masked="false"` attribute). The package will toggle visibility using the `display-none` utility class from the U.S. Web Design System.
+
+```html
+<span id="masked-text">
+  <span data-masked="true">
+    6**-**-***4
+  </span>
+  <span class="display-none" data-masked="false">
+    666-12-1234
+  </span>
+</span>
+<input type="checkbox" aria-controls="masked-text">
+```

app/javascript/packages/memorable-date/README.md

@@ -0,0 +1,22 @@
+# `@18f/identity-memorable-date`
+
+Custom element implementing behaviors associated with Login.gov's adaptation of the U.S. Web Design System [Memorable Date component](https://designsystem.digital.gov/components/memorable-date/).
+
+## Usage
+
+Importing the element will register the `<lg-memorable-date>` custom element:
+
+```ts
+import '@18f/identity-memorable-date/memorable-date-element';
+```
+
+The custom element will implement modal behavior, but all markup must already exist.
+
+```html
+<lg-memorable-date>
+  <script type="application/json" class="memorable-date__error-strings"></script>
+  <input type="text" class="memorable-date__month" />
+  <input type="text" class="memorable-date__day" />
+  <input type="text" class="memorable-date__year" />
+</lg-memorable-date>
+```

app/javascript/packages/password-confirmation/README.md

@@ -1,4 +1,4 @@
-# `@18f/password-confirmation`
+# `@18f/identity-password-confirmation`
 
 Custom element implementation that adds password inputs with validation for confirmation.
 
@@ -7,7 +7,7 @@ Custom element implementation that adds password inputs with validation for conf
 Importing the element will register the `<lg-password-confirmation>` custom element:
 
 ```ts
-import '@18f/password-confirmation/password-confirmation-element';
+import '@18f/identity-password-confirmation/password-confirmation-element';
 ```
 
 The custom element will implement the behavior for validation, but all markup must already exist.

app/javascript/packages/password-toggle/README.md

@@ -0,0 +1,22 @@
+# `@18f/identity-password-toggle`
+
+Custom element implementation that toggles the visibility of a password field text in response to clicking a checkbox.
+
+## Usage
+
+Importing the element will register the `<lg-password-toggle>` custom element:
+
+```ts
+import '@18f/identity-password-toggle/password-toggle-element';
+```
+
+The custom element will implement associatd behaviors, but all markup must already exist.
+
+```html
+<lg-password-toggle>
+  <label for="password">Password</label>
+  <input id="password" class="password-toggle__input">
+  <input id="toggle" type="checkbox" class="password-toggle__toggle" aria-controls="password">
+  <label for="toggle" class="password-toggle__toggle-label">Show password</label>
+</lg-password-toggle>
+```

app/javascript/packages/phone-input/README.md

@@ -0,0 +1,31 @@
+# `@18f/identity-phone-input`
+
+Custom element implementation initializes an interactive phone input, using [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input).
+
+## Usage
+
+Importing the element will register the `<lg-phone-input>` custom element:
+
+```ts
+import '@18f/identity-phone-input';
+```
+
+The custom element will implement associatd behaviors, but all markup must already exist.
+
+```html
+<lg-phone-input data-delivery-methods="[&quot;sms&quot;,&quot;voice&quot;]" data-translated-country-code-names="{&quot;us&quot;:&quot;United States&quot;}" data-captcha-exempt-countries="[&quot;US&quot;]">
+  <script type="application/json" class="phone-input__strings">{"country_code_label":"Country code","invalid_phone_us":"Enter a 10 digit phone number.","invalid_phone_international":"Enter a phone number with the correct number of digits.","unsupported_country":"We are unable to verify phone numbers from %{location}"}</script>
+  <div class="phone-input__international-code-wrapper">
+    <label for="international-code">Country code</label>
+    <select
+      id="international-code"
+      class="phone-input__international-code"
+      data-countries="[&quot;US&quot;]"
+    >
+      <option data-supports-sms="true" data-supports-voice="true" data-country-code="1" data-country-name="United States" value="US">United States +1</option>
+    </select>
+  </div>
+  <label for="phone-number">Phone number</label>
+  <input id="phone-number" class="phone-input__number">
+</lg-phone-input>
+```

app/javascript/packages/spinner-button/README.md

@@ -0,0 +1,38 @@
+# `@18f/identity-spinner-button`
+
+Custom element and React component for displaying a spinner effect on a button when clicked.
+
+## Usage
+
+### Custom Element
+
+Importing the element will register the `<lg-spinner-button>` custom element:
+
+```ts
+import '@18f/identity-spinner-button/spinner-button-element';
+```
+
+The custom element will implement associated behaviors, but all markup must already exist, rendered server-side or by the included React component.
+
+When clicked, the a `spinner-button--spinner-active` class will be added to the root element, which can be used to control the visibility of associated elements using custom CSS styles.
+
+```html
+<lg-spinner-button long-duration-wait-ms="15000">
+  <button>
+    <span class="spinner-button__content">Click Me</span>
+  </button>
+</lg-spinner-button>
+```
+
+### React
+
+The package exports a `<SpinnerButton />` component.
+
+```tsx
+import { render } from 'react-dom';
+import { SpinnerButton } from '@18f/identity-spinner-button';
+
+const appRoot = document.getElementById('app-root');
+
+render(<SpinnerButton>Spin!</SpinnerButton>, appRoot)
+```

app/javascript/packages/time-element/README.md

@@ -0,0 +1,21 @@
+# `@18f/identity-time-element`
+
+Custom element which converts a time string rendered by the server into the user's local time.
+
+## Usage
+
+The package exports a `TimeElement` custom element, which can be registered using the browser's custom element registry:
+
+```ts
+import { TimeElement } from '@18f/identity-time-element';
+
+customElements.define('lg-time', TimeElement);
+```
+
+The custom element will implement associated behaviors, but all markup must already exist.
+
+```html
+<lg-time data-timestamp="2023-09-26T20:20:26Z" data-format="%{month} %{day}, %{year} at %{hour}:%{minute} %{day_period}">
+  September 26, 2023 at 4:20 PM
+</lg-time>
+```

app/javascript/packages/validated-field/README.md

@@ -0,0 +1,45 @@
+# `@18f/identity-validated-field`
+
+Custom element and React component for controlling validation behavior associated with a form input.
+
+It enhances the behavior of an input by:
+
+- Displaying an error message on the page when form submission results in a validation error
+- Moving focus to the first invalid field when form submission results in a validation error
+- Providing default error messages for common validation constraints (e.g. required field missing)
+- Allowing you to customize error messages associated with default field validation
+- Resetting the error state when an input value changes
+
+## Usage
+
+### Custom Element
+
+Importing the element will register the `<lg-validated-field>` custom element:
+
+```ts
+import '@18f/identity-validated-field/validated-field-element';
+```
+
+The custom element will implement associated behaviors, but all markup must already exist, rendered server-side or by the included React component.
+
+```html
+<lg-validated-field error-id="validated-field-error-b6a88605">
+  <script type="application/json" class="validated-field__error-strings">{"valueMissing":"This field is required"}</script>
+  <div class="validated-field__input-wrapper">
+    <input class="validated-field__input" aria-invalid="false" required="required">
+  </div>
+</lg-validated-field>
+```
+
+### React
+
+The package exports a `<ValidatedField />` component. If rendered without a child, it will render a text input by default.
+
+```tsx
+import { render } from 'react-dom';
+import { ValidatedField } from '@18f/identity-validated-field';
+
+const appRoot = document.getElementById('app-root');
+
+render(<ValidatedField />, appRoot);
+```