@globalpayments-private/gpds-pattern-web 0.0.0-stage → 0.1.0-pr.7.gdcb74cd

package/README.md

@@ -1,3 +1,568 @@
-# Temporary Holding Version
+# gpds-pattern-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GP pattern library for Web — domain-neutral application patterns composed from
+UDS components. Native parity ships separately as `gpds-pattern-native`.
+
+Patterns are authored as [Stencil](https://stenciljs.com) web components so they
+can be consumed from React, Angular, Vue or plain HTML. See
+[ADR 0001](docs/adr/0001-web-component-framework.md) for that decision and
+[ADR 0002](docs/adr/0002-provider-driven-patterns.md) for the API shape.
+
+> **Naming.** Custom elements use the `gp-` prefix and CSS custom properties use
+> `--uds-pattern-*`. The Stencil namespace remains `gpds-pattern-web` to match the
+> repository; the package is published as
+> [`@globalpayments-private/gpds-pattern-web`](https://www.npmjs.com/package/@globalpayments-private/gpds-pattern-web).
+
+## Design principles
+
+1. **Patterns own the workflow.** A pattern internalises step sequencing, busy
+   state, failure copy, throttling and focus management. Consumers do not
+   reimplement those per portal — that duplication is the problem the library
+   exists to remove.
+2. **Consumers own their platform, via a Provider.** Integration is a thin
+   adapter implementing a provider contract. The library ships **zero SDK code**
+   and never holds credentials or tokens.
+3. **Capabilities, not configuration.** Which optional provider methods you
+   implement determines which routes render. There is no way to show a link the
+   backend cannot service.
+4. **Compose the design system; never re-implement it.** Every control inside a
+   pattern is a Vega element. A primitive we copy is a primitive that stops
+   receiving the design system's accessibility and contrast fixes — see
+   [ADR 0004](docs/adr/0004-compose-design-system-and-renderer-slimmers.md).
+   Patterns own *layout*, and style it through the `--uds-pattern-*` custom properties in
+   [`src/global/tokens.css`](src/global/tokens.css).
+5. **Copy is overridable.** Every user-facing string — including error copy —
+   is exposed through `config.labels` so patterns localise without forking.
+
+## Live demo
+
+A browsable demo is published to GitHub Pages from `main` by
+[`.github/workflows/demo-pages.yml`](.github/workflows/demo-pages.yml).
+
+**Nothing is published to npm to make that work.** The workflow builds the
+library from source and serves the compiled bundle next to the page, so looking
+at a component never requires cutting a release. Vega comes from the public
+registry at build time like any other dependency.
+
+The demo runs the real compiled component — not a mock — and lets you switch
+between adapters to see the claim that *capabilities are the configuration*:
+
+| Scenario | What it shows |
+| --- | --- |
+| Full journey | password → MFA method → one-time code |
+| One MFA method | the picker is skipped, because one option is not a choice |
+| Sign-in only | recovery and sign-up links are *absent*, as the adapter lacks those methods |
+| Lockout after 1 failure | the terminal locked step |
+| Localised (es) | `config.labels` overrides, with Vega still owning field-level validation copy |
+| Control strategy | sign-up intercepted and handed to the host |
+
+An event panel shows everything a host application would receive. Validation
+failures never appear there, which is the visible proof that `vega-form` gates
+submission before the adapter is called.
+
+The demo shows *behaviour*, not the code a host would write. Beside it,
+**Open as editable source** launches
+[`vega-sandbox`](https://github.com/heartlandpayments/vega-sandbox), which runs
+a real `npm install` and Vite dev server in the browser — the integration code
+on the left, the same card rendering on the right. It needed no fork and no Nx
+migration, only a library that can actually be installed from a browser, which
+is what [publishing](#publishing) unblocked.
+
+The project it opens is generated at build time by `npm run build:sandbox` and
+pinned to the exact version that build published, so the source shown is the
+source running. It opens in a new tab rather than an iframe because
+WebContainers need cross-origin isolation, which an iframe can only inherit
+from its top-level page. On `main` the link is replaced by a note until a
+release is cut — the sandbox can only install versions that exist. See
+[ADR 0007](docs/adr/0007-code-and-preview-in-the-demo.md).
+
+### Per-PR previews
+
+Every pull request gets its own demo, so a change can be looked at before it
+merges:
+
+| URL | What it is |
+| --- | --- |
+| `/` | the latest commit on `main` |
+| `/pr-<number>/` | that pull request, rebuilt on every push |
+
+A bot comment on the PR links to its preview, and the preview directory is
+deleted when the PR closes.
+
+This works because a repository has **exactly one** Pages site. The official
+`actions/deploy-pages` route replaces that whole site with a single artifact,
+so a preview deploy and a `main` deploy would overwrite each other —
+whichever ran last would win. Instead both publish as *directories* on the
+`gh-pages` branch: a `main` publish deliberately preserves every `pr-*`
+directory, and a preview publish only ever touches its own. Both workflows
+share one concurrency group, because they push to the same branch. See
+[ADR 0006](docs/adr/0006-github-pages-preview-strategy.md).
+
+## Getting started
+
+### Install (consumers)
+
+```bash
+npm install @globalpayments-private/gpds-pattern-web @globalpayments/vega
+```
+
+Vega is a **peer dependency** — a consuming app already has it, and bundling a
+second copy would register the custom elements twice.
+
+### Develop (this repository)
+
+```bash
+npm install
+npm start          # dev server with the demo at src/index.html
+npm run build      # production build + generated component docs
+npm test           # spec tests
+npm run test:coverage  # spec tests with the enforced coverage thresholds
+npm run e2e           # build, serve the React host, run the Cypress suite against it
+```
+
+The demo signs in with `ada@example.com` / `correct-horse`, then any security
+code of `555555`. Three wrong passwords demonstrates the lockout branch.
+
+> **`postinstall` patches `@stencil/core`.** Slimmers need it in order to use
+> field initialisers at all; without it every slimmer throws at construction in
+> a built bundle while the spec suite stays green. See
+> [ADR 0005](docs/adr/0005-patch-stencil-for-slimmers.md).
+
+### Publishing
+
+[`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml)
+publishes to the public npm registry. Push a tag matching `package.json`:
+
+```bash
+npm version patch      # or minor / major / prerelease
+git push --follow-tags
+```
+
+It can also be run from the Actions tab, with a **dry-run** option that builds,
+packs and verifies the tarball without publishing.
+
+The workflow refuses to publish when the tag disagrees with `package.json`,
+when that version is already on the registry, or when the packed tarball is
+missing an entry point — and it publishes *the tarball it just inspected*, so
+what is verified is what ships. A version containing a `-` is treated as a
+prerelease and goes to the `next` dist-tag, never `latest`.
+
+#### Per-PR preview releases
+
+Every push to a pull request publishes the commit under review as a prerelease,
+**before** that PR's demo page is deployed:
+
+```
+0.1.1-pr.6.g2cf3c93      immutable, pinned to one commit
+pr-6                     dist-tag, follows the PR head
+```
+
+Without this the preview would be half-stale: the page is rebuilt from the
+branch, but the sandbox beside it installs from the registry, so it would show
+the last *released* code while the live card above it showed the change under
+review — with nothing on screen admitting the difference. The Pages deploy is
+therefore gated on the publish succeeding, and records what it is demonstrating
+in `demo-meta.json` next to the page.
+
+Both are retired when the PR closes: the dist-tag is removed and the versions
+are deprecated. The versions themselves remain — npm versions are immutable and
+cannot be withdrawn after 72 hours.
+
+> **Preview builds of unmerged branches are published to a public registry.**
+> That is inherent to the WebContainer sandbox, which can only install what has
+> actually been published. Forks never publish — they have no access to the
+> token.
+
+#### Shared publish logic
+
+Release and preview differ only in which version and which dist-tag. Everything
+else — install, pack, verify, publish — lives once in
+[`.github/actions/npm-publish`](.github/actions/npm-publish/action.yml), a
+composite action both call, so a guard cannot be fixed in one path and
+forgotten in the other.
+
+One of those guards exists because it was missed: npm assigns `latest`
+implicitly when a package has no `latest` tag yet, regardless of the `--tag`
+given, so the first preview publish left `npm install` returning a PR build.
+The action now checks `latest` after publishing a prerelease and moves it back
+to the newest real release, warning when there is not one to move it to.
+
+> **Until a release tag is cut, there is no stable version.** `latest`
+> currently resolves to a preview. Cutting `v0.1.0` fixes that and is also
+> what enables the sandbox link on the `main` demo.
+
+> **The scope is `@globalpayments-private`, but the package is public.** An npm
+> scope is an organisation and a token grants write to specific organisations;
+> ours is for the `globalpayments-private` org, so that is the scope. Package
+> visibility is independent of the org's name, and `access: public` here is
+> deliberate — an unauthenticated `npm install` inside a WebContainer is the
+> whole point (ADR 0007), and a `restricted` package would silently break it.
+> Publishing needs the `NPM_JS_REGISTRY_ACCESS_TOKEN` repository secret.
+
+## Patterns
+
+| Element | Purpose |
+| --- | --- |
+| [`uds-pattern-login-card`](src/components/uds-pattern-login-card/readme.md) | The full login workflow — sign-in, sign-up, MFA, OTP, password reset, username recovery, lockout. |
+| [`uds-pattern-login-page`](src/components/uds-pattern-login-page/readme.md) | Centred, responsive page shell for an unauthenticated route. |
+
+Each component's `readme.md` is the **generated API reference** — props,
+events, methods and slots, rewritten by `stencil build --docs` on every build.
+Hand-written guidance lives alongside it so the build cannot destroy it:
+
+📖 **[`uds-pattern-login-card` usage guide](src/components/uds-pattern-login-card/usage.md)**
+— worked adapters for real identity platforms, React / Angular / Vue recipes,
+control-strategy patterns, localisation, theming and a troubleshooting table.
+
+## Integrating `uds-pattern-login-card`
+
+The entire integration is one adapter. You do not route steps, toggle spinners
+or write failure messages.
+
+```ts
+import type { UdsAuthProvider } from '@globalpayments-private/gpds-pattern-web';
+
+const auth: UdsAuthProvider = {
+  // The only required method.
+  async signIn({ identifier, password }) {
+    const res = await myIdp.authenticate(identifier, password);
+
+    if (res.challenge === 'PASSWORD') return { status: 'password_required' };
+    if (res.challenge === 'MFA') return { status: 'mfa_required', methods: res.factors };
+    if (res.error === 'NOT_FOUND') return { status: 'error', code: 'account_not_found' };
+
+    return { status: 'success', session: { identifier, accessToken: res.token } };
+  },
+
+  // Optional methods are capabilities. Implementing `requestPasswordReset`
+  // is what makes "Forgot password?" appear.
+  async requestPasswordReset({ identifier }) {
+    await myIdp.sendResetLink(identifier);
+    return { status: 'reset_link_sent', destination: maskEmail(identifier) };
+  },
+};
+
+document.querySelector('uds-pattern-login-card').auth = auth;
+```
+
+```html
+<uds-pattern-login-page logo-src="/logo.svg" logo-alt="Global Payments">
+  <uds-pattern-login-card></uds-pattern-login-card>
+</uds-pattern-login-page>
+```
+
+The pattern's `--uds-pattern-*` tokens ship as a **separate global stylesheet**,
+so registering the elements is not on its own enough — import it once, at the
+host app's entry point:
+
+```ts
+import '@globalpayments-private/gpds-pattern-web/tokens.css';
+```
+
+Without it every custom property is undefined, which makes each `var()` invalid
+at computed-value time: the card loses its spacing, surface and typography
+while still rendering and behaving correctly, so nothing errors to point at the
+cause. Override the tokens by redeclaring them on `:root` *after* this import.
+
+Listen for the outcome:
+
+```ts
+card.addEventListener('udsLoginSuccess', e => router.go('/dashboard', e.detail.session));
+```
+
+### Provider capabilities
+
+| Implement | Unlocks |
+| --- | --- |
+| `signIn` *(required)* | the workflow itself |
+| `verifyPassword` | a dedicated password step (otherwise `signIn` is re-called with both fields) |
+| `selectMfaMethod` | the MFA method picker (auto-skipped when there is only one method) |
+| `verifyOtp` | security-code entry |
+| `resendOtp` | the throttled "Resend code" affordance |
+| `requestPasswordReset` / `resetPassword` | "Forgot password?" and the new-password step |
+| `requestUsernameReminder` | "Forgot username?" |
+| `signUp` | the "Create one" route |
+
+### Error handling
+
+Adapters return a `UdsAuthErrorCode`, never a message. The pattern maps codes to
+approved copy, so raw IdP strings never reach a user. Override any of them:
+
+```html
+<uds-pattern-login-card config='{"labels":{"errors":{"account_not_found":"No encontramos esa cuenta."}}}'></uds-pattern-login-card>
+```
+
+### Validation
+
+Form validation is `vega-form`'s, not the pattern's. Its submit handler awaits
+`valid()` across every field it controls and only emits `vegaFormSubmit` once
+they all pass, so an invalid step never reaches your adapter — and the field at
+fault is the thing that reports it, in the design system's error presentation.
+
+Fields declare what they need and Vega derives the rest, including the wording:
+
+| Declared | Gives you |
+| --- | --- |
+| `required` | required rule, the asterisk on the label, "This field is required" |
+| `type="email"` | email-format rule and "Please enter the correct email format." |
+
+Only two checks cannot be expressed that way, so they live in
+[`validation/login-validation-rules.ts`](src/components/uds-pattern-login-card/validation/login-validation-rules.ts):
+
+- **`MatchesFieldRule`** — "confirm new password" must equal "new password". It
+  depends on a sibling field, so no single-field rule can state it.
+- **`CompleteCodeRule`** — `required` only asks whether a value is non-empty, so
+  a half-typed security code would satisfy it and reach the provider.
+
+The card still raises a banner, but only for what a *provider* returns — those
+are workflow outcomes, not field errors, and they have no field to attach to.
+
+## Customisation: the escape-hatch ladder
+
+Reach for the lowest level that solves your problem (architecture doc §8):
+
+| Level | Mechanism | Use when |
+| --- | --- | --- |
+| 1 | Named slots (`brand`, `footer`) | injecting your own content |
+| 2 | CSS custom properties (`--uds-pattern-*`, plus Vega's own) | re-theming |
+| 3 | `config.auth` — a `UdsAuthProvider` | adapting to your identity platform |
+| 4 | `config.control` — a `UdsLoginControlStrategy` | the course of the workflow genuinely differs |
+| 5 | Composition in a layout container | rearranging the page |
+| 6 | Fork | last resort; please open an issue first |
+
+Two things that used to be on this ladder are deliberately **not** here any more
+— see [ADR 0003](docs/adr/0003-aggregate-customisation-seams.md):
+
+- **Atomic override props** (`controlled` / `step` / `loading` / `error-message`)
+  are gone. Customising behaviour through a handful of independent props means a
+  new path only works if you remember to set *all* of them; miss one and you get
+  a half-configured workflow that still renders. The replacement is a single
+  aggregate seam.
+- **CSS `::part` exposure** is gone. A `::part` rule accepts arbitrary
+  declarations, so it can hide the error alert, remove a focus ring or break
+  contrast — guardrails the design system is accountable for. Custom properties
+  stay, because they constrain the *value* rather than handing over the
+  declaration.
+
+### `UdsLoginControlStrategy`
+
+One object with an interceptor at every checkpoint the workflow has. Each hook
+receives `next()` — the pattern's own behaviour — so you adapt a decision rather
+than reimplement the machine, and a strategy that only observes cannot
+accidentally change the flow.
+
+| Checkpoint | Fires | Default |
+| --- | --- | --- |
+| `submit` | before the provider is consulted | calls the provider method for the step |
+| `transition` | on every provider result | maps the result to a step |
+| `navigate` | on every step change | performs the move |
+| `failure` | on every failure | maps the error code to approved copy |
+| `complete` | on success | emits `udsLoginSuccess` |
+
+```ts
+import { goTo, stay } from '@globalpayments-private/gpds-pattern-web';
+
+card.config = {
+  auth,
+  control: {
+  // Hand sign-up off to your own journey.
+  navigate: (ctx, next) => {
+    if (ctx.to === 'sign-up') {
+      router.push('/register');
+      return stay();
+    }
+    return next();
+  },
+
+  // Insert a consent gate ahead of the password reset.
+  transition: (ctx, next) => {
+    const outcome = next();
+    return outcome.type === 'goto' && outcome.step === 'reset-password' && !consented
+      ? goTo('check-email')
+      : outcome;
+    },
+  },
+};
+```
+
+Because every checkpoint lives in one object, a new path is expressed — and
+reviewed — as a whole. That is the point: it pushes both us and the consumer to
+reason at the workflow level, which is where a pattern library earns its keep.
+
+## Architecture: slimmers
+
+The card's behaviour is split across small single-responsibility classes
+(*slimmers*) that bind to the component's state declaratively, rather than
+living in one large component file:
+
+```
+src/components/uds-pattern-login-card/
+  uds-pattern-login-card.tsx                props, events, state, render shell
+  slimmers/
+    login-workflow.slimmer.ts      the state machine
+    resend-throttle.slimmer.ts     the resend window and countdown
+    identity-memory.slimmer.ts     remembered-identifier persistence
+    renderers/
+      login-card-renderer.tsx      card chrome: heading, banner, form
+      login-step-renderer.tsx      the body of the current step
+      login-field-renderer.tsx     the Vega controls themselves
+  view-model/
+    login-step.view-model.ts       what to show, derived in one place
+    login-card-handlers.ts         what a renderer may ask for
+```
+
+Rendering uses the same mechanism, in `slimmers/renderers/` — the convention
+Vega itself follows. A renderer binds to the component's `viewModel` and
+`handlers` with `@MapToComponentField()` and types them by indexing the
+component class, so it cannot drift out of step with what the component exposes.
+Renderers only read; every mutation goes back through `handlers`.
+
+The DI framework behind this is in [`src/slimmer/`](src/slimmer/README.md),
+ported from the legacy Vega design system's *Vega Slimmer* (VD-1102 / VCD-20).
+
+It is vendored here only until it can be depended on. The framework has since
+been extracted on the design-system side as `@gpds-web/slimmer`
+(`packages/slimmer` in `gpds-web`), but that package is currently private and
+unpublished, so this repository cannot consume it yet. When it ships,
+`src/slimmer/` should be deleted in favour of the dependency — every import
+already goes through `src/slimmer/index.ts`, so the swap is a dependency change
+rather than a refactor. See
+[ADR 0005](docs/adr/0005-patch-stencil-for-slimmers.md).
+
+## Testing
+
+Two suites, with different jobs.
+
+```bash
+npm test                # spec tests
+npm run test:coverage   # the same suite, with coverage thresholds enforced
+npm run e2e             # build + serve the React host + drive it with Cypress
+```
+
+### Spec tests
+
+Workflow behaviour is tested through `createMemoryAuthProvider()`, a reference
+fake IdP that is also the clearest worked example of an adapter.
+
+Spec tests assert the *contract*, not our markup — which Vega elements we
+render, what we configure them with, and what we do when they report a change.
+Vega's real classes are deliberately **not** registered in `newSpecPage`: that
+would pull the design system's dependency graph into our unit tests and break
+them whenever Vega changed something internal.
+
+#### Coverage
+
+`npm run test:coverage` fails the build below the thresholds in
+`stencil.config.ts`. The bar is **100% of statements, branches, functions and
+lines, globally, with no per-file exceptions.**
+
+That is deliberate. A per-file relaxation hides the interesting question —
+*why* is this branch unreachable? — behind a number. Every exception this
+suite used to carry turned out to be either dead code or a missing test, and
+none of them survived the question:
+
+| Was excused | What it actually was |
+| --- | --- |
+| `focusFirstControl`'s `?.` chains | Defensive code for a missing shadow root on a `shadow: true` component, and a missing `.card__heading` that every step renders. Both deleted, with a comment recording why they cannot happen. |
+| `result.methods ?? []` (×2) | `UdsAuthResult` declares `methods` as **required** on the `mfa_required` arm and `parseAuthResult` asserts it. Dead code. Deleted. |
+| `textField`'s `required = true` default | Unused configuration — no caller ever overrode it. The option was removed. The same probe found `autocomplete = 'off'` in the same state; since autofill is the difference between a password manager working and silently not, it was made **required** instead of defaulted. |
+| `login-step-renderer`'s `default:` arm | Genuinely unreachable *through the card* — terminal steps are routed elsewhere — but reachable by binding the slimmer to a plain host directly. Now covered by a test. |
+| `errors[code] ?? errors.unknown` | Impossible by type, but reachable in practice: a server-driven label override expresses a missing translation as `null`, which spreads a hole into the merged map. Kept, and now covered by a test. |
+
+No `istanbul ignore` comments were needed. If one ever is, it belongs on the
+single line with a comment explaining the impossibility — not on a whole file.
+
+### End-to-end tests
+
+The spec boundary — everything that depends on Vega's real classes — has to be
+checked in a real browser. Doing so has caught five bugs that every spec passed
+through: `vega-button[type="submit"]` being unable to submit a native ancestor
+`<form>` across its shadow boundary; loose `vega-selection-tile` elements
+throwing on unmount without their group ancestor; and a slimmer without an
+explicit constructor rendering an entirely **empty component** while all 74
+specs stayed green (now fixed at source — ADR 0005).
+
+The Cypress suite in [`cypress/`](cypress) closes that gap, and it drives a
+**React application** — [`e2e-app/`](e2e-app) — rather than a static page.
+
+That is the point. The static demo proves the component works; a React host
+proves the component is *integrable*, and React 18 is where custom elements
+actually bite:
+
+- **Object props stringify.** React 18 sets any prop it does not recognise as
+  an attribute, so `config={adapter}` arrives as the string
+  `"[object Object]"`. The config has to be assigned to the element *property*,
+  from a `ref`.
+- **Custom events have no JSX surface.** `onUdsLoginSuccess` is not a thing;
+  `udsLoginStepChange` and friends need `addEventListener`.
+
+Both live in [`e2e-app/src/useLoginCard.ts`](e2e-app/src/useLoginCard.ts), which
+is as close to documentation of the React integration as it is test
+scaffolding. Standing it up immediately found two bugs the static demo could
+never have: the package's `exports` map pointed `import` at
+`dist/esm/index.mjs`, a file the build does not emit — so **every ESM consumer
+importing the package by name failed to resolve it** — and a listener effect
+keyed on a ref rather than the element went deaf after a remount.
+
+The app consumes the **built package**, not `src/`, through a `file:..`
+dependency that npm installs as a symlink. There is no bundler alias, so what
+Cypress drives is exactly what a consumer would install, `exports` map included
+— which is why the broken entry point surfaced at all.
+
+The static demo at `src/index.html` is untouched and still what GitHub Pages
+publishes; it is now a demo rather than a test fixture.
+
+> Vite + React rather than Next.js: SSR has no bearing on what this suite
+> checks, and custom elements under Next would need `ssr: false` dynamic
+> imports throughout — ceremony that tests the workaround, not the component.
+> Say the word if a Next host is wanted and it can be swapped in.
+
+```bash
+npm run e2e               # one shot: build package, build app, serve, run, stop
+# or, against a server you are already running:
+npm run e2e-app:build
+npm run serve:e2e-app &
+npm run cypress:run       # headless
+npm run cypress:open      # interactive
+```
+
+What it covers: the full journey (identifier → password → MFA choice → code →
+signed in), capability-driven rendering, the lockout branch, localisation,
+control-strategy interception, and validation gating — each invalid submit
+asserted to reach the adapter **zero** times, read off the host's event log.
+
+Two things to know before writing more specs:
+
+- **`includeShadowDom: true`** is set in `cypress.config.ts` and is not
+  optional: everything this library renders lives inside a shadow root.
+- **Text inputs are typed into with `{ force: true }`.** Cypress 13 misreads an
+  `<input>` reached through two shadow roots as non-focusable, although the
+  same element passes `:not([disabled])`, `be.visible` and `.click()`. The
+  keystrokes are real; only the pre-flight check is wrong. `cy.fillField()`
+  already handles this.
+- **`vega-input-passcode` is driven through its `vegaChange` event**, not
+  keystrokes. Typing into its boxes — or dispatching a bare `input` event at
+  them — hangs the renderer indefinitely. That reproduces on a standalone,
+  *uncontrolled* `vega-input-passcode` on an otherwise empty page, so it is a
+  Vega-side interaction with synthetic events rather than anything this pattern
+  introduces. `cy.fillPasscode()` wraps the workaround.
+
+#### Linux prerequisites
+
+Cypress needs an X server and a few shared libraries that a bare container does
+not have:
+
+```bash
+sudo apt-get install -y xvfb libgtk-3-0 libgbm1 libnotify4 libnss3 libxss1 libasound2
+```
+
+#### CI
+
+**Not wired up yet, deliberately.** `gpds-pattern-web` has two registered
+workflows (`demo-pages.yml`, `demo-preview-cleanup.yml`), both `active`, and
+**neither has ever produced a run** — including on the push to `main` that
+merged them. `gpds-web` has no workflows at all and no in-repo pipeline
+definition, so there is no existing Cypress CI setup to mirror. Both suites are
+single commands (`npm run test:coverage`, `npm run e2e`) and are ready to
+be dropped into whichever system actually runs; adding a config that silently
+never executes would be worse than leaving this blank.

package/dist/cjs/control-strategy-DhhYTbse.js

@@ -0,0 +1,113 @@
+'use strict';
+
+/**
+ * Default (en-US) copy for the login workflow pattern.
+ *
+ * Wording mirrors the approved Global Payments sign-in design
+ * (Figma: "Design System and Pilot Portals Rollout", node 14:2748 / 14:2765).
+ *
+ * The `errors` map is part of the pattern, not the consumer: shipping approved
+ * failure copy is how every GP product ends up failing in the same words.
+ */
+const DEFAULT_LOGIN_LABELS = {
+    identifierHeading: 'Sign In to My Account',
+    identifierFieldLabel: 'Email address',
+    rememberIdentifier: 'Remember my email',
+    passwordHeading: 'Enter your password',
+    passwordFieldLabel: 'Password',
+    showPassword: 'Show password',
+    hidePassword: 'Hide password',
+    forgotPassword: 'Forgot password?',
+    forgotUsername: 'Forgot username?',
+    mfaMethodHeading: 'How do you want to receive your security code?',
+    mfaMethodDescription: 'Choose a delivery method to continue signing in.',
+    otpHeading: 'Verify your security code',
+    otpDescription: 'Enter the security code generated from your authenticator app.',
+    otpDescriptionForMethod: 'Enter the security code sent via {method}.',
+    otpFieldLabel: 'Security code',
+    otpIncomplete: 'Enter all {count} digits of your security code.',
+    otpSubmit: 'Verify and sign in',
+    showCode: 'Show security code',
+    hideCode: 'Hide security code',
+    resendCode: 'Resend code',
+    resendCodeIn: 'Resend code in {seconds}s',
+    changeMfaMethodPrompt: 'Want to change how you receive your security code?',
+    changeMfaMethod: 'Change security method',
+    forgotPasswordHeading: 'Reset your password',
+    forgotPasswordDescription: 'Enter your email address and we will send you a link to reset your password.',
+    forgotUsernameHeading: 'Find your username',
+    forgotUsernameDescription: 'Enter the email address associated with your account.',
+    checkEmailHeading: 'Check your email',
+    checkEmailDescription: 'If an account matches what you entered, we have sent you an email with next steps.',
+    checkEmailDescriptionWithDestination: 'If an account matches {destination}, we have sent an email with next steps.',
+    lockedHeading: 'Your account is temporarily locked',
+    lockedDescription: 'For your security we have paused sign-in after too many attempts. Try again later.',
+    lockedDescriptionWithTime: 'For your security we have paused sign-in after too many attempts. Try again in {minutes} minutes.',
+    resetPasswordHeading: 'Create a new password',
+    newPasswordFieldLabel: 'New password',
+    confirmPasswordFieldLabel: 'Confirm new password',
+    signUpHeading: 'Create your account',
+    signUpDescription: 'Tell us a little about you to get started.',
+    firstNameFieldLabel: 'First name',
+    lastNameFieldLabel: 'Last name',
+    signUpSubmit: 'Create account',
+    haveAccountPrompt: 'Already have an account?',
+    signIn: 'Sign in',
+    successHeading: "You're signed in",
+    continue: 'Continue',
+    back: 'Back',
+    troubleSigningInPrompt: 'Forgot password? Account locked? Change security method?',
+    troubleSigningIn: 'Trouble Signing In?',
+    helpPrompt: 'Need help signing in? Check out our',
+    help: 'Login help',
+    noAccountPrompt: "Don't have an account?",
+    createAccount: 'Create one',
+    errors: {
+        invalid_credentials: "That email address and password don't match. Try again.",
+        invalid_identifier: 'Enter a valid email address.',
+        invalid_code: "That security code isn't right. Check it and try again.",
+        code_expired: 'That security code has expired. Request a new one.',
+        account_locked: 'Your account is temporarily locked. Try again later.',
+        account_not_found: "We couldn't find an account for that email address.",
+        account_exists: 'An account already exists for that email address.',
+        password_policy: "That password doesn't meet the security requirements.",
+        passwords_do_not_match: "Those passwords don't match.",
+        rate_limited: 'Too many attempts. Wait a moment and try again.',
+        network: "We couldn't reach the server. Check your connection and try again.",
+        unknown: 'Something went wrong. Try again.',
+    },
+};
+/** Substitutes `{name}` placeholders in a label template. */
+function formatLabel(template, values) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => key in values ? String(values[key]) : match);
+}
+
+/** Moves the workflow to `step`. */
+const goTo = (step) => ({ type: 'goto', step });
+/** Leaves the workflow where it is. */
+const stay = () => ({ type: 'stay' });
+/** Surfaces a failure without moving. */
+const fail = (code, message) => ({
+    type: 'fail',
+    code,
+    message,
+});
+/**
+ * Runs a checkpoint through the strategy, falling back to the pattern's own
+ * behaviour when the strategy does not intercept it.
+ */
+function intercept(interceptor, context, fallback) {
+    return interceptor ? interceptor(context, fallback) : fallback();
+}
+/** Identity helper giving a strategy literal its types without a type annotation. */
+function createControlStrategy(strategy) {
+    return strategy;
+}
+
+exports.DEFAULT_LOGIN_LABELS = DEFAULT_LOGIN_LABELS;
+exports.createControlStrategy = createControlStrategy;
+exports.fail = fail;
+exports.formatLabel = formatLabel;
+exports.goTo = goTo;
+exports.intercept = intercept;
+exports.stay = stay;