Ontario.ca Search Components Package

This package contains the ontario.ca search bar and the associated autosuggest dropdown for it.

Development

To make development of the NPM package simpler, we have added a hot reload local server workflow to the project. It's very simple.

1. Install all the required NPM packages by issuing npm install from this folder
2. Run npm run start to build the development bundle and serve it with hot reload

Note that in order to make this work as expected, we have created separate Webpack files to handle the two scenarios.

Packaging & Deployment

NPM Package Deployment (Automated)

NPM release preparation is automated via GitLab CI.

To publish a new version of the package:

• Ensure your changes are merged into the main branch
• Use Conventional Commits with the (npm-components) scope, for example:
  • feat(npm-components): add autocomplete
  • fix(npm-components): fix crash

What happens automatically

Once changes are merged into main, the CI pipeline will:

• Analyze commits since the last release
• Filter commits to scope (npm-components) only
• Determine the version bump:
  • feat(npm-components) -> minor
  • fix(npm-components) -> patch
  • BREAKING CHANGE or ! -> major
• Update the version in packaged-components/package.json
• Generate/update packaged-components/CHANGELOG.md
• Create and push a git tag in the format:
  • npm-vX.Y.Z
• Trigger a pipeline that builds the package

Publishing to NPM

• The pipeline prepares the package automatically
• Publishing is a manual approval step in GitLab (npm-publish:prod)
• Once that job succeeds, the package is available on NPM

Important Notes

• Only commits with (npm-components) scope trigger a release
• No release will occur if there are no relevant commits
• Do not manually run npm run npm-publish
• Do not manually create npm-v tags

Manual Override (Optional)

If needed, a release can still be triggered manually:

git tag npm-v1.2.3
git push origin npm-v1.2.3

Package Use In Projects

To use the NPM package in your own project, you need to do the following:

1. Import the package into your project
2. Add server configuration as a script tag on the page like this:

  <script>      // This is the configuration for the ElasticSearch AppSearch Connector
      window.apiConfig = {
          searchKey: "search-XXXXXXX",
          engineName: "XXXXXXX-search",
          endpointBase: "https://XXXXXXX.ent.us-east-1.aws.found.io"
      }
      // This is the endpoint configuration for the search results page for EN and FR
      window.endpointConfig = {
          en: "/search/search-results/",
          fr: "/fr/recherche/resultats-de-recherche/"
      }
  </script>

3. Import the JS from the NPM package into the page via a script tag
4. Create an element on the page for the NPM package to hook into. This element should have id of ontario-search-autosuggest

Example:

<div id="ontario-search-autosuggest" className="ontario-header__search-container ontario-columns ontario-small-10 ontario-medium-offset-3 ontario-medium-6 ontario-large-offset-0 ontario-large-6">...</div>

Tips and other things to consider when using this package

• Please recieve the proper apiConfig from the Ontario.ca Search team.
• The package must be imported/loaded after the DOM is loaded.
• Add the design system classes to the anchor element.
• We have implemented this package into our own Ontario.ca Search Autosuggest repository, it may be helpful to take a look!
• There may be some minor CSS changes needed.
• Make sure the mobile searchOpen/searchClose buttons work as expected with the package imported. This includes focus being moved to the input on button click.
• It is recommended to nest a simple search bar in the element as a backup in-case this package does not load. You would just need to make the submission send the user to https://www.ontario.ca/search/search-results/?query=QUERY and https://www.ontario.ca/fr/recherche/resultats-de-recherche/?query=QUERY Here is an example from the Ontario Design System of a simple search bar: https://designsystem.ontario.ca/components/detail/search-box.html