Merge pull request #227 from US-CBP/feature/combobox

update docs, minor bugfixes

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

@@ -9,6 +9,22 @@ body:has(cbp-app[data-cbp-theme="dark"]) {
   background-color: var(--cbp-color-branding-cbp-dark);
 }
 
+
+/* Docs overrides */
+.sbdocs .sbdocs-content {
+  max-width: 1200px !important;
+}
+
+.sbdocs code {
+  white-space: normal !important;
+}
+
+.sbdocs table {
+  width: 100% !important;
+}
+
+
+
 /* TechDebt: Remove when table component is added to design tokens story */
 #design-tokens table {
   width: 100%;

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

@@ -17,11 +17,16 @@ export class CbpApp {
   /** Optionally specifies light/dark mode. This is only needed if the application can change the theme separate from OS settings.  */
   @Prop({reflect: true}) theme: "light" | "dark" | "system" = "system"
 
+  /** Turning on debug mode will log the version of the design system package and Stencil version it was built with to the console, in addition to application name and version, if specified. */
   @Prop({reflect: true}) debug: boolean;
 
+  /** Specifies the application name for logging with debug information. */
   @Prop({reflect: true}) appName: string;
+
+  /** Specifies the application version for logging with debug information. This may be automated by importing it from the application's package.json, if used. */
   @Prop({reflect: true}) appVersion: string;
 
+
   handleThemeChange(mql) {
     this.theme = mql.matches ? "dark" : "light";
   }

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

@@ -1,6 +1,9 @@
 import { Component, Prop, Element, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - The slotted badge content should be a short 1-2 digit number.
+ */
 @Component({
   tag: 'cbp-badge',
   styleUrl: 'cbp-badge.scss'
@@ -9,6 +12,7 @@ export class CbpBadge {
 
   @Element() host: HTMLElement;
 
+  /** Specifies a color variant. Currently the only variant supported is "danger". */
   @Prop({ reflect: true }) color: 'default' | 'danger';
 
   /** 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. */

packages/web-components/src/components/cbp-button/cbp-button.scss

@@ -127,6 +127,7 @@ cbp-button {
     min-height: var(--cbp-button-min-height);
     width: var(--cbp-button-width);
     height: var(--cbp-button-height);
+    white-space: nowrap;
     cursor: pointer;
 
     color: var(--cbp-button-color);

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

@@ -52,7 +52,8 @@ export class CbpButton {
 
   /** Specifies if the button is pressed and results in `aria-pressed="true"` being placed on the button when true. Only valid on actual `button` elements. */
   @Prop() pressed: boolean;
-  /** Specifies if a controlled UI widget is expanded and results in `aria-pressed="true"` being placed on the button when true.
+  /** 
+   * Specifies if a controlled UI widget is expanded and results in `aria-pressed="true"` being placed on the button when true.
    * This property is usually used for progressive disclosure patterns such as accordions, menus, expand/collapse, etc., where
    * focus remains on the control after the user action.
    */
@@ -86,6 +87,7 @@ export class CbpButton {
 
   /** A custom event emitted when the click event occurs for either a rendered button or anchor/link. */
   @Event() buttonClick!: EventEmitter;
+
   /** A custom event emitted when the component has completed loading and its internal lifecycles. */
   @Event() componentLoad!: EventEmitter;
 

packages/web-components/src/components/cbp-checkbox/cbp-checkbox.scss

@@ -108,7 +108,7 @@ cbp-checkbox {
 
   label {
     display: grid;
-    grid-template-columns: var(--cbp-space-7x) 1fr;
+    grid-template-columns: var(--cbp-space-6x) 1fr;
     align-items: center;
     gap: var(--cbp-space-2x);
     min-height: var(--cbp-checkbox-min-height);

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

@@ -3,7 +3,7 @@ import { setCSSProps} from '../../utils/utils';
 
 
 /**
- * @slot - the checkbox control and label text goes in the default slot, both of which are placed inside of the `label` element. The label should not include excessively long descriptive text.
+ * @slot - the checkbox control and label text are placed in the default slot, both of which are rendered inside of the `label` element. The label should not include excessively long descriptive text.
  */
 @Component({
   tag: 'cbp-checkbox',
@@ -40,7 +40,7 @@ export class CbpCheckbox {
 
   //this.formField.indeterminate=true;
 
-  /** A custom event emitted when the click event occurs for either a rendered button or anchor/link. */
+  /** A custom event emitted when the checked state changes due to user interaction. */
   @Event() stateChanged: EventEmitter;
   handleChange() {
     this.checked=this.formField.checked;
@@ -77,7 +77,6 @@ export class CbpCheckbox {
 
     // query the DOM for the slotted form field and wire it up for accessibility and attach an event listener to it
     this.formField = this.host.querySelector('input[type=checkbox]');
-
     if (this.formField) {
       this.formField.addEventListener('change', () => this.handleChange());
     }

packages/web-components/src/components/cbp-grid-item/cbp-grid-item.tsx

@@ -1,25 +1,39 @@
 import { Component, Prop, Element, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/** @slot - The default slot may contain any content representing the grid item. */
 @Component({
   tag: 'cbp-grid-item',
   styleUrl: 'cbp-grid-item.scss',
 })
 export class CbpGridItem {
   @Element() host: HTMLElement;
 
+  /** Specifies the starting position/edge of the grid item in the horizontal/column plane, which is used to calculate the size (including column and row spanning) and location within the grid. */
   @Prop() gridColumnStart: number | string;
+
+  /** Specifies the ending position/edge (non-inclusive) of the grid item in the horizontal/column plane, which is used to calculate the size (including column and row spanning) and location within the grid. */
   @Prop() gridColumnEnd: number | string;
+
+  /** Specifies the starting position/edge of the grid item in the vertical/row plane, which is used to calculate the size (including column and row spanning) and location within the grid. */
   @Prop() gridRowStart: number | string;
+
+  /** Specifies the ending position/edge (non-inclusive) of the grid item in the vertical/row plane, which is used to calculate the size (including column and row spanning) and location within the grid. */
   @Prop() gridRowEnd: number | string;
+
+  /** Aligns this specific grid item in the vertical/column axis, perpendicular to the inline axis, separate from the parent context.  */
   @Prop() alignSelf: string;
+
+  /** Justifies this specific grid item content horizontally, along the inline/row axis, separate from the parent context. */
   @Prop() justifySelf: string;
+
   /** Names the Grid Area for use with grid-template-area on the parent. */
   @Prop() gridArea: string;
 
   /** Supports adding inline styles as an object */
   @Prop() sx: any = {};
 
+
   componentWillLoad() {
     if (typeof this.sx == 'string') {
       this.sx = JSON.parse(this.sx) || {};

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

@@ -1,7 +1,7 @@
 import { Component, Prop, Element, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
-//** @slot - The default slot accepts grid items. These should be DOM nodes; inserting plain text nodes as a direct descendant of the grid will yield unexpected results. */
+/** @slot - The default slot accepts grid items. These should be `cbp-grid-item` components or DOM nodes; inserting plain text nodes as a direct descendant of the grid may yield unexpected results. */
 @Component({
   tag: 'cbp-grid',
   styleUrl: 'cbp-grid.scss',
@@ -12,31 +12,37 @@ export class CbpGrid {
   /** Specifies the grid display. Defaults to "grid". */
   @Prop({ reflect: true }) display: 'grid' | 'inline-grid' = 'grid';
 
-  /** Defines the grid via named grid areas, which provides a visualization of the structure of the grid. */
+  /** Defines the grid via named grid areas (providing a visualization of the structure of the grid), which are not associated with any particular grid item, but can be referenced from the grid-placement properties. */
   @Prop() gridTemplateAreas: string;
-  /** Specifies the track sizing functions (and optionally line names) of the grid columns as a space-separated track list */
+
+  /** Specifies the track sizing functions (and optionally line names) of the grid columns as a space-separated track list. */
   @Prop() gridTemplateColumns: 'none' | string;
-  /** Specifies the track sizing functions (and optionally line names) of the grid rows as a space-separated track list */
+
+  /** Specifies the track sizing functions (and optionally line names) of the grid rows as a space-separated track list. */
   @Prop() gridTemplateRows: 'none' | string;
 
   /** Specifies how auto-placed items get flowed into the grid. */
-  @Prop() gridAutoFlow: 'row' | 'column' | 'row-dense' | 'column dense';
-  /** Specifies the size of implicitly-created columns using the auto-placement algorithm. */
+  @Prop() gridAutoFlow: 'row' | 'column' | 'row dense' | 'column dense';
+
+  /** Specifies the size (in CSS units) of implicitly-created columns using the auto-placement algorithm. */
   @Prop() gridAutoColumns: string;
-  /** Specifies the size of implicitly-created rows using the auto-placement algorithm. */
+
+  /** Specifies the size (in CSS units) of implicitly-created rows using the auto-placement algorithm. */
   @Prop() gridAutoRows: string;
 
   /** Aligns grid items in the vertical/column axis, perpendicular to the inline axis.  */
   @Prop() alignItems: 'normal' | 'stretch' | 'center' | 'start' | 'end' | 'self-start' | 'self-end' | 'baseline' | 'first baseline' | 'last baseline';
+
   /** Justifies grid content horizontally, along the inline/row axis. */
   @Prop() justifyItems: 'legacy' | 'normal' | 'stretch' | 'center' | 'safe center' | 'unsafe center' | 'start' | 'end' | 'self-start' | 'self-end' | 'left' | 'right' | 'baseline' | 'first baseline' | 'last baseline';
 
   /** Aligns grid content vertically when total grid size is smaller than container. */
   @Prop() alignContent: 'normal' | 'stretch' | 'center' | 'start' | 'end' | 'space-around' | 'space-between' | 'space-evenly' | 'safe center' | 'unsafe center';
+
   /** Justifies grid content horizontally when total grid size is smaller than container. */
   @Prop() justifyContent: 'normal' | 'stretch' | 'center' | 'start' | 'end' | 'left' | 'right' | 'space-around' | 'space-between' | 'space-evenly' | 'safe center' | 'unsafe center';
 
-  /** Specifies the spacing between grid items in the form of a single value or space-separated row-gap and column-gap values in CSS units */
+  /** Specifies the spacing between grid items in the form of a single value or space-separated row-gap and column-gap values (in CSS units). */
   @Prop() gap: string;
 
   /** The size (in CSS units; preferably relative units such as `rem`) below which the grid items linearize. */

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

@@ -14,8 +14,10 @@ export class CbpSection {
 
   /** Specifies the tag to render. Use `section` with the `accessibilityText` property to make an accessible landmark element. */
   @Prop() tag: 'div' | 'section' | 'none' = 'none';
-  /** Specifies an accessible label to make a `section` tag an accessible landmark element. Likely has no effect otherwise. */
+
+  /** Specifies an accessible label as `aria-label` to make a `section` tag an accessible landmark element. Likely has no effect otherwise. */
   @Prop() accessibilityText: string;
+
   /** Supports adding inline styles as an object */
   @Prop() sx: any = {};
 

packages/web-components/src/components/cbp-segmented-button-group/cbp-segmented-button-group.tsx

@@ -1,6 +1,7 @@
 import { Component, Prop, Element, Event, EventEmitter, Listen, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/** @slot - Only `cbp-button` components should be slotted within the default slot to make up the button group. */
 @Component({
   tag: 'cbp-segmented-button-group',
   styleUrl: 'cbp-segmented-button-group.scss'
@@ -12,8 +13,13 @@ export class SegmentedButtonGroup {
 
   @Element() host: HTMLElement;
 
+  /** Specifies whether multiple buttons may be activated at the same time. Defaults to false. */
   @Prop() multiple: boolean;
+
+  /** Specifies accessibility text used to label the group, applied to the group via aria-label. */
   @Prop() accessibilityText: string;
+
+  /* TODO: not yet implemented  */
   @Prop() disabled: boolean;
 
   /** Supports adding inline styles as an object */

packages/web-components/src/components/cbp-skip-nav/cbp-skip-nav.specs.mdx

@@ -31,7 +31,7 @@ The Skip Navigation link (or "Skip Nav") is an essential accessibility feature t
 * The target element of the Skip Nav link should have a `tabindex="-1"` applied to it if it is not a natively interactive element.
 * If the target is not a landmark element, it must have an accessible name.
 * The target element must not be hidden from view in any way (beware of floating navbars, footers, and other overlays).
-* The default verbiage of "skip to main content" is preferable due to pronunciation and should only be changed when using multiple Skip Nav links in order to differentiate them.
+* The default verbiage of "Skip to main content" is preferable due to pronunciation and should only be changed when using multiple Skip Nav links in order to differentiate them.
 
 ### Additional Notes and Considerations
 

packages/web-components/src/components/cbp-skip-nav/cbp-skip-nav.tsx

@@ -1,6 +1,9 @@
 import { Component, Prop, Element, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - The default slot accepts custom link text, which is only needed if multiple skip links are present. Otherwise, it is advised to use the default "Skip to main content", which has been validated for clarity and pronunciation.
+ */
 @Component({
   tag: 'cbp-skip-nav',
   styleUrl: 'cbp-skip-nav.scss'
@@ -11,8 +14,12 @@ export class CbpSkipNav {
 
   @Element() host: HTMLElement;
 
+  /** Specifies the target `id` where focus is sent when the "skip nav" link is activated. Defaults to "main". */
   @Prop() targetId: string = "main";
+
+  /** Specifies a shortcut key, which is applied as an `accessKey` attribute. */
   @Prop() shortcutKey: string;
+
   /** Supports adding inline styles as an object */
   @Prop() sx: any = {};
 

packages/web-components/src/components/cbp-tab-panel/cbp-tab-panel.tsx

@@ -1,6 +1,9 @@
 import { Component, Element, Prop, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - The default slot holds the contents of a tab panel, which may include any form of text, markup, and media elements.
+ */
 @Component({
   tag: 'cbp-tab-panel',
   styleUrl: 'cbp-tab-panel.scss'

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

@@ -1,6 +1,9 @@
 import { Component, Element, Prop, Event, EventEmitter, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - The default slot holds the tab's label (rendered as a button label), which may include text as well as icons, badges, and tags.
+ */
 @Component({
   tag: 'cbp-tab',
   styleUrl: 'cbp-tab.scss'

packages/web-components/src/components/cbp-tabs/cbp-tabs.scss

@@ -39,7 +39,10 @@
  * @prop --cbp-tab-color-border-selected-dark: var(--cbp-color-interactive-active-light);
 
  * @prop --cbp-tab-border-radius: 0;
-*/
+
+ * @prop --cbp-tab-color-outline-focus: var(--cbp-color-white);
+ * @prop --cbp-tab-color-outline-focus-dark: var(--cbp-color-black);
+ */
 :root {
   --cbp-tabs-color-border: var(--cbp-color-gray-cool-30);
   --cbp-tabs-color-border-dark: var(--cbp-color-gray-cool-60);

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

@@ -1,6 +1,9 @@
 import { Component, Element, Prop, Host, h } from '@stencil/core';
 import { setCSSProps } from '../../utils/utils';
 
+/**
+ * @slot - Only `cbp-tab` components shall be slotted within the default slot.
+ */
 @Component({
   tag: 'cbp-tabs',
   styleUrl: 'cbp-tabs.scss',