Merge pull request #284 from US-CBP/bugfix/docs-20250424

Bugfix/docs 20250424

Author: dgibson666

packages/web-components/CHANGELOG.md

@@ -6,10 +6,13 @@ The React components are wrappers generated from this package and will share the
 
 ## [unpublished] TBD
 
+* Updated `cbp-drawer` to add the ability to persist its contents in the flow of the page at a certain breakpoint, mobilizing to an overlay below that breakpoint.
+* Updated the Passenger List archetype to demonstrate this drawer functionality.
 * Updated the `cbp-dropdown` faux button so that the chevron can be rotated when opened.
 * Updated web components readme and included it Storybook under "Using the web components."
 
 ## [0.0.1-develop.20] 04-18-2025
+
 * First cut of the `cbp-slider` component for selecting a single value from a range.
 * First cut of the `cbp-code-snippet` component, which is used to display code samples.
 * Updates to the `cbp-dropdown` component to:
@@ -25,6 +28,7 @@ The React components are wrappers generated from this package and will share the
 * Added tag badges (beta, new, etc.) to stories via plugin.
 
 ## [0.0.1-develop.19] 02-12-2025
+
 * First cut of the `cbp-subnav` and `cbp-subnav-item` components.
 * First cut of the `cbp-file-input` component, supporting only the native web functionality with enhancements to come later.
 * First cut of the `cbp-loader` component.
@@ -35,13 +39,15 @@ The React components are wrappers generated from this package and will share the
 * Minor bugfixes/updates to `cbp-radio` and `cbp-checkbox`.
 
 ## [0.0.1-develop.18] 01-14-2025
+
 * First cut of the `cbp-toggle` component, which acts like a visual treatment for a checkbox.
 * First cut of the `cbp-multicol` component, a component-based implementation of multi-column layout used in checklist and radiolist stories.
 * Created stories for horizontal checklists and radio lists using `cbp-flex`.
 * Decoupled fonts from `cbp-app` for performance testing. They are now included in the package as assets and should be loaded as external resources from the /assets/css files.
 * Minor bugfixes/updates to `cbp-dropdown` and `cbp-checkbox`.
 
 ## [0.0.1-develop.17] 12-12-2024
+
 * First cut of the `cbp-nav-item` component for including navigation links in the Application Header.
 * BREAKING: updated the `cbp-app-header` implementation. The pattern now uses the new `cbp-nav-item` component for the first "Application Name" link. Code should be updated from Storybook for the latest implementation.
 * First cut of the `cbp-table` component.
@@ -55,6 +61,7 @@ The React components are wrappers generated from this package and will share the
 * Published Stencil-generated component API docs to Storybook. We will continually revisit these for completion.
 
 ## [0.0.1-develop.16] 10-28-2024
+
 * First cut of `cbp-checkbox`.
 * First cut of `cbp-radio`.
 * First cut of `cbp-toast`.

packages/web-components/assets/css/storybook-canvas.css

@@ -25,29 +25,4 @@ body:has(cbp-app[data-cbp-theme="dark"]) {
 
 .sbdocs table {
   width: 100% !important;
-}
-
-
-
-/* TechDebt: Remove when table component is added to design tokens story */
-#design-tokens table {
-  width: 100%;
-  border-collapse: collapse;
-  border: solid 1px #999;
-  margin-block-end: 2rem;
-}
-
-#design-tokens tr {
-  border-block-end: solid 1px #999;
-}
-
-
-#design-tokens th,
-#design-tokens td {
-  text-align: left;
-  width: 33.3%;
-  padding: .5rem;
-  margin: 0;
-  border: 0;
-  border-block-end: solid 1px #999;
-}
+}

packages/web-components/assets/images/confirm-Roboto.png

@@ -1,8 +1,10 @@
-# Including the CBP Design System Web Components
+# Using the CBP Design System Web Components
+
+## Including the Web Components in Your Application
 
-There are a couple strategies for including the CBP Design System web components in your site or application, detailed below. 
+There are a couple strategies for including the CBP Design System web components in your site or application, detailed below.
 
-## Node Modules
+### Node Modules
 
 The CBP Design System [web components](https://www.npmjs.com/package/@cbpds/web-components) (and [React wrappers](https://www.npmjs.com/package/@cbpds/react-components)) are published to npm.
 
@@ -18,14 +20,14 @@ import { defineCustomElements } from '@cbpds/web-components/dist/esm/loader.js';
 defineCustomElements();
 ```
 
-## Script tag
+### Script tag
 
 For sites not running in a node.js environment or requiring a build step, the web components may be included via script tag:
 
 - Put a script tag referencing the loader module in the head of your index.html or template file.
-    - This file is a loader, which registers all of the design system components and lazy-loads individual components as needed.
-    - Note: ESM modules must be delivered over SSL/https.
-    - Then you can use the web components (custom elements) anywhere in your template, JSX, html, etc.
+  - This file is a loader, which registers all of the design system components and lazy-loads individual components as needed.
+  - Note: ESM modules must be delivered over SSL/https.
+  - Then you can use the web components (custom elements) anywhere in your template, JSX, html, etc.
 
 You can use UNPKG (an open source global content delivery network that mirrors npm) for testing, but it should never be used for production apps.
 
@@ -47,15 +49,27 @@ Ideally, your application should reference an central, organization-hosted copy
 <script type="module" src="./assets/cbp-web-components/cbp-web-components.esm.js"></script>
 ```
 
-# Using the CBP Design System Web Components
+## Using the Web Components
 
 Once the CBP Design System web components have been included in your site or application, the are used like any other HTML elements - they are custom elements, after all.
 
 It is recommended that the [`cbp-app` web component](https://us-cbp.github.io/design-system/?path=/docs/components-app-specifications--docs) is used to wrap the entire contents of your application or site template to include the global CSS variables (design tokens) that are used throughout the design system for styling the components.
 
 To get started quickly, you may copy the markup from one of our ["template" stories](https://us-cbp.github.io/design-system/?path=/story/patterns-page-templates--internal) to wrap your application or site content.
 
-# Fonts and Assets
+Here's an example of a button component:
+
+```
+<cbp-button
+  type="button"
+  fill="solid"
+  color="primary"
+>
+  Default
+</cbp-button>
+```
+
+## Fonts and Assets
 
 Regardless of how you include the web components (either method above), you'll still need some assets that are part of the CBP Design System package but are not encapsulated in the `cbp-app` web component or any others:
 
@@ -71,4 +85,15 @@ Copy and paste the following into your index.html or template file:
 <link rel="stylesheet" type="text/css" href="./assets/css/roboto_mono.css">
 ```
 
-If the path to your application's assets folder is different than `"./assets"`, you may need to provide the paths as properties of the `cbp-universal-header` component as part of your site/application template.
+These CSS files assume a directory structure of:
+
+- webroot
+  - assets
+  - css
+    - fonts
+      - roboto
+      - roboto-mono
+
+Any deviations from this structure may require editing of the linked CSS files and paths to the fonts.
+
+If the path to your application's assets folder is different than `"./assets"`, you may also need to provide the paths as properties of the `cbp-universal-header` component as part of your site/application template.

packages/web-components/readme.md

@@ -1,14 +1,14 @@
 import { Component, Prop, Element, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - Accordion Items shall be slotted in the default slot. While other content may be included within the default slot, it is not recommended.
+ */
 @Component({
   tag: 'cbp-accordion',
   styleUrl: 'cbp-accordion.scss',
 })
 
-/**
- * @slot - Accordion Items shall be slotted in the default slot. While other content may be included within the default slot, it is not recommended.
- */
 export class CbpAccordion {
   private items: HTMLCbpAccordionItemElement[];
 

packages/web-components/src/components/cbp-accordion/cbp-accordion.tsx

@@ -1,26 +1,25 @@
 /**
+ * @prop --cbp-action-bar-color-dark: var(--cbp-color-text-lightest);
  * @prop --cbp-action-bar-color-background: var(--cbp-color-grey-cool-70);
- * @prop--cbp-action-bar-color-background-dark: var(--cbp-color-grey-cool-5);
-*/
-//todo: swap light and dark values so context works correctly
+ * @prop --cbp-action-bar-color-background-dark: var(--cbp-color-grey-cool-5);
+ * @prop --cbp-action-bar-color: var(--cbp-color-text-darkest);
+ */
 :root {
---cbp-action-bar-color-background: var(--cbp-color-gray-cool-5);
---cbp-action-bar-color-background-dark: var(--cbp-color-gray-cool-70);
-
---cbp-action-bar-color: var(--cbp-color-text-darkest);
---cbp-action-bar-color-dark: var(--cbp-color-text-lightest);
-
+  --cbp-action-bar-color: var(--cbp-color-text-darkest);
+  --cbp-action-bar-color-dark: var(--cbp-color-text-lightest);
+  --cbp-action-bar-color-background: var(--cbp-color-gray-cool-5);
+  --cbp-action-bar-color-background-dark: var(--cbp-color-gray-cool-70);
 }
 
-[data-cbp-theme=light] cbp-action-bar[context*=dark]:not([context=light-always]),
-[data-cbp-theme=dark] cbp-action-bar:not([context=dark-inverts]):not([context=light-always]) {
-  --cbp-action-bar-color-background: var(--cbp-action-bar-color-background-dark);
+[data-cbp-theme='light'] cbp-action-bar[context*='dark']:not([context='light-always']),
+[data-cbp-theme='dark'] cbp-action-bar:not([context='dark-inverts']):not([context='light-always']) {
   --cbp-action-bar-color: var(--cbp-action-bar-color-dark);
-  
+  --cbp-action-bar-color-background: var(--cbp-action-bar-color-background-dark);
 }
 
 cbp-action-bar {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   justify-content: right;
   min-height: var(--cbp-space-14x);
@@ -30,17 +29,15 @@ cbp-action-bar {
   background-color: var(--cbp-action-bar-color-background);
   gap: var(--cbp-space-3x);
 
-   & > *[slot="cbp-action-bar-info"]{
+  & > *[slot=cbp-action-bar-info] {
     margin-inline-end: auto;
-   }
-   /*
-   *** Sticky variant position
-   */
-   &[variant=floating] {
+  }
+
+  &[variant=floating] {
     position: fixed;
     bottom: 0;
     left: 0;
     padding-inline: var(--cbp-responsive-spacing-outer);
     box-shadow: var(--cbp-shadow-level-3-up);
-   }
+  }
 }

packages/web-components/src/components/cbp-action-bar/cbp-action-bar.scss

@@ -6,28 +6,29 @@ import { Meta } from '@storybook/addon-docs';
 
 ## Purpose
 
-The Action bar serves several purposes, the most common use case is a submission bar in a form page. Alternatively the bar can be used to
- contain tools that affect the content of the page the user is on.
+The Action Bar acts as a container for form controls (buttons) or other tools to affect the content of the page.
 
 ## Functional Requirements
 
-* The Action bar is a container with slots for a status or text description of the action bar and a slot for the buttons/links to be displayed
-* Action bar comes with 2 variants, inline & floating.
-    *inline: is rendered inplace. Primarily for supporting Forms, strucutred list footer, grids, etc 
-    *floating: is rendered at bottom of viewport, used for containing tools that affect the content of the whole page the user is viewing
+* The Action Bar is a container with slots for a status or text description as well as controls.
+  * The descriptive text in the named slot is aligned left.
+  * The controls are aligned to the right.
+* The Action Bar has two variants - inline and floating.
+  * The inline variant is teh default and renders in the flow of the document.
+  * The floating variant is rendered at bottom of viewport, primarily tools that affect the content of the whole page.
 
 ### Responsiveness
 
-* Since content is slotted into the action bar the end user can alter/add items to hide, alter as needed for Responsiveness
-* Inline variant is designed to follow the overall responsiveness of the control/container it is in so that behavior does not conflict 
-    with these other controls
-* Sticky variant utilizes responsive padding variables to adjust as per overall design system breakpoints
+* The Action Bar will fill 100% of the screen (floating) or parent (inline).
+* The Action Bar will wrap as needed at smaller screen sizes, but... 
+* It is up to the developer to make sure its contents are fully responsive.
+* The sticky variant uses the responsive padding token to adjust outer padding at the same ratio as other template elements.
 
 ### Accessibility
 
-* Action bar as a container does not recieve focus, it also does not inhibit the native Accessibility of any of the slotted content.
-    Thus consumers will need to ensure that any slotted content is accessibile (CBP components will come with this natively) 
+* The action bar itself does not receive focus and the accessibility of its slotted contents are the responsibility of those components.
+* When using the floating variant, it is important that the component be placed logically in the source code order so that its controls and content exist in the proper place in the document and tab order.
 
 ### Additional Notes and Considerations
 
-* it is not advised to use both inline and floating action bar on the same page to avoid user confusion
+* In order to avoid user confusion, it is not advised to use both inline and floating action bar on the same page.

packages/web-components/src/components/cbp-action-bar/cbp-action-bar.specs.mdx

@@ -1,14 +1,18 @@
 import { Component, Host, Element, Prop, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - Any controls or content may be slotted into the default slot and will be aligned to the right of the bar.
+ * @slot cbp-action-bar-info - This named slot is intended for information placed before the default slot content, aligned to the left of the bar.
+ */
 @Component({
   tag: 'cbp-action-bar',
   styleUrl: 'cbp-action-bar.scss',
 })
 export class CbpActionBar {
   @Element() host: HTMLElement;
 
-  /** variant for type: floating/inline */
+  /** Specifies whether the action bar is inline or floating. Defaults to inline. */
   @Prop({ reflect: true }) variant:  'inline' | 'floating' = 'inline'
 
   /** Specifies the context of the component as it applies to the visual design and whether it inverts when light/dark mode is toggled. Default behavior is "light-inverts" and does not have to be specified. */
@@ -34,5 +38,4 @@ export class CbpActionBar {
       </Host>
     );
   }
-
 }

packages/web-components/src/components/cbp-action-bar/cbp-action-bar.tsx

@@ -6,7 +6,7 @@ import { Component, Prop, Host, h, Env } from '@stencil/core';
 */
 
 /**
- *  @slot - All application markup should be placed within the default slot to inherit the base CSS, fonts, and dark mode styling.
+ *  @slot - All application markup should be placed within the default slot to inherit the base CSS, design tokens, and dark mode styling.
  */
 @Component({
   tag: 'cbp-app',

packages/web-components/src/components/cbp-app/cbp-app.tsx

@@ -1,5 +1,4 @@
 /**
- * @prop --cbp-badge-color: var(--cbp-color-text-lightest);
  * @prop --cbp-badge-color: var(--cbp-color-text-lightest);
  * @prop --cbp-badge-color-dark: var(--cbp-color-text-darkest);
  * @prop --cbp-badge-color-background: var(--cbp-color-info-base);
@@ -16,8 +15,6 @@
 [data-cbp-theme=dark] cbp-badge:not([context=dark-inverts]):not([context=light-always]) {
   --cbp-badge-color: var(--cbp-badge-color-dark);
   --cbp-badge-color-background: var(--cbp-badge-color-background-dark);
-  
-  --cbp-badge-color-background-danger: var(--cbp-badge-color-background-danger-dark);
 }
 
 cbp-badge {