### Install Sam Design System Core Packages via npm
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/pages/introduction/introduction.component.html
This command installs the primary Sam Design System Angular component libraries, including core components, layout utilities, and Formly extensions. The `--save` flag ensures these packages are added as dependencies to your project's `package.json` file.
```shell
npm install --save @gsa-sam/components @gsa-sam/layouts @gsa-sam/sam-formly
```
--------------------------------
### Install and Configure GitHub Release Notes (gren)
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
Instructions for installing the `gren` npm package globally to generate GitHub release notes. Requires a GitHub personal access token with 'repo' scope.
```Shell
npm install -g gren
```
--------------------------------
### Sam Design System Available Packages API Reference
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/pages/introduction/introduction.component.html
This section provides an API-like reference for the various Angular component packages available within the Sam Design System. It details each package's purpose and indicates the structure for its required and peer dependencies.
```APIDOC
Package: @gsa-sam/components
Description: Beta.SAM.gov common Angular components (e.g. accordion, modal dialog, tables, etc)
Dependencies: (dynamic, specified by item.key@item.value)
Peer Dependencies: (dynamic, specified by item.key@item.value)
Package: @gsa-sam/sam-formly
Description: Beta.SAM.gov form elements based on ngx-formly (e.g. input, select, date picker, etc)
Dependencies: (dynamic, specified by item.key@item.value)
Peer Dependencies: (dynamic, specified by item.key@item.value)
Package: @gsa-sam/sam-material-extensions
Description: Beta.SAM.gov elements extending Angular Material CDK
Dependencies: (dynamic, specified by item.key@item.value)
Peer Dependencies: (dynamic, specified by item.key@item.value)
```
--------------------------------
### Run Angular Development Server
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
Starts a local development server for an Angular application. The application will automatically reload in the browser upon changes to source files.
```Shell
ng serve --project=myapp
```
--------------------------------
### Configure Angular Documentation Module Routes and Imports
Source: https://github.com/gsa/sam-design-system/blob/master/CONTRIBUTING.md
This JavaScript code demonstrates how to configure the main `DocumentationModule` in an Angular application. It shows importing various feature modules and components, defining application routes using `RouterModule.forChild`, and registering these modules and routes within the `@NgModule` decorator. This setup is crucial for integrating new example components and their associated routes into the overall documentation structure.
```javascript
import { IntroductionModule } from './pages/introduction/introduction.module';
import { IntroductionComponent } from './pages/introduction/introduction.component';
import { OverviewModule } from './pages/overview/overview.module';
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { RouterModule, Routes } from '@angular/router';
import { DocumentationSharedModule } from './shared';
import { OverviewComponent } from './pages/overview/overview.component';
import { ROUTES as HEADER_ROUTES, HeaderModule } from './components/header/header.module'; // Import your ROUTES and Module
declare var require: any;
export const ROUTES: Routes = [
{ path: '', pathMatch: 'full', redirectTo: 'components/header' },
{ path: 'overview', component: OverviewComponent },
{ path: 'introduction', component: IntroductionComponent },
{ path: 'components', pathMatch: 'full', redirectTo: 'components/alert' },
{ path: 'components/header', children: HEADER_ROUTES }, // Add your example component routes (the last segment should match the registered demo list name)
];
@NgModule({
imports: [
CommonModule,
DocumentationSharedModule,
RouterModule.forChild(ROUTES),
HeaderModule, // Add your example component module to the imports array
OverviewModule,
IntroductionModule,
]
})
export class DocumentationModule {
}
```
--------------------------------
### Template Variable and Function Usage
Source: https://github.com/gsa/sam-design-system/blob/master/libs/packages/sam-formly/src/lib/formly/types/file-input.html
These snippets illustrate basic data binding and function invocation within a templating engine. They show how to access object properties, including dynamic property access, and how to call functions with arguments to render dynamic content.
```Templating
{{column.label}}
{{props.noDataText}}
{{element[column.property]}} {{column.text}} {{column.textFn(element)}}
```
--------------------------------
### Custom CSS for SdsTabsModule Styling
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tabs/demos/styling/tabs-styling.component.html
Provides example CSS rules for customizing the visual appearance of the `SdsTabsModule`. This includes styling the tab container, individual tab items, selected states, and the content panel by leveraging the custom class passed via `tabClass`.
```CSS
.sds-tabs--example { flex-flow: row-reverse; display: -webkit-box; display: -ms-flexbox; display: flex; border-bottom: 1px solid #81aefc; }
.sds-tabs--example .sds-tabs__item { background-color: #eff6fb; }
.sds-tabs--example .sds-tabs__item[aria-selected='true'] { background-color: white; border-bottom: none; }
.sds-tabs--example + .sds-tabs__content { background-color: #eff6fb; }
```
--------------------------------
### SAM.gov Design System Documentation Library Structure
Source: https://github.com/gsa/sam-design-system/blob/master/CONTRIBUTING.md
Details the internal file structure of the `documentation` library within the SAM.gov Design System, highlighting component examples, API documentation output, and shared utilities.
```Shell
documentation/src/lib
├── apidoc
│ ├── sam-design-system-site-e2e
│ └── sam-design-system-site
├── components
│ ├── example-component
| | ├── demos
| | | ├── basic
| | | | ├── example-component-basic.component.html
| | | | ├── example-component-basic.component.scss
| | | | ├── example-component-basic.component.ts
| | | | ├── example-component-basic.module.ts
| | | | └── readme.md
| | | └── advanced
| | | ├── example-component-advanced.component.html
| | | ├── example-component-advanced.component.scss
| | | ├── example-component-advanced.component.ts
| | | ├── example-component-advanced.module.ts
| | | └── readme.md
| | ├── opening.md
| | ├── example-component.module.ts
| | └── closing.md
│ └── shared
├── pages
│ ├── introduction
│ └── overview
├── shared
│ ├── component-wrapper
│ ├── highlight
│ └── index.ts
└── documentation.module.js
```
--------------------------------
### Angular Template Interpolation Example
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/icons/demos/basic/icons-basic.component.html
A basic example of Angular's template interpolation syntax, used to display the value of an element from an array within the HTML template.
```HTML
{{ displayName[i] }}
```
--------------------------------
### sdsDate Pipe Formatting Examples
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/date-pipe/demos/basic/date-pipe-basic/date-pipe-basic.component.html
Examples demonstrating how the `sdsDate` pipe formats dates based on their relation to the current date. It automatically adjusts the display format to show time, month/day, or full date.
```Angular Template
{{ today | sdsDate }}
```
```Angular Template
{{ currentYearDate | sdsDate }}
```
```Angular Template
{{ previouseYearDate | sdsDate }}
```
--------------------------------
### Configure Angular Module for Icon Selection
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/utilities/icons/icons-basic/icons-basic.component.html
After importing, the `NgxBootstrapIconsModule` must be added to your `@NgModule` imports. Its `pick` function is then called with an object containing all the specific icons you wish to make available for use in your components.
```TypeScript
@NgModule({
imports: [
CommonModule,
IconModule,
NgxBootstrapIconsModule.pick({add, square})
],
declarations: [YourComponent],
exports: [YourComponent]
})
```
--------------------------------
### SDS External Link Directive API Reference and Usage Examples
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/external-link/demos/basic/external-link-basic.component.html
Provides an API reference for the `SdsExternalLinkDirective`, detailing its configuration options and demonstrating various use cases for external, FSD, and email links, including considerations for icon visibility and ARIA labels.
```APIDOC
SDS External Link Directive:
Purpose: Manages external links, providing consistent styling and behavior.
Configuration Options:
hideIcon: boolean
Description: When set to 'true', hides the external link icon typically displayed next to the link.
Example: hideIcon: true
Usage Examples:
Standard External Link:
[Acquisition.gov](https://Acquisition.gov)
External Link with Hidden Icon:
Description: Demonstrates hiding the external link icon.
[USASpending.GOV](https://USASpending.gov)
Configuration: hideIcon: true
FSD Considered External Link (as of @version 10.0.21):
Description: Example of an FSD (Federal Service Desk) considered external link.
[FSD.GOV](https://fsd.gov/test)
Aria Label Attached to Link (no new window indication):
Description: Shows a link with an ARIA label that does not explicitly indicate opening in a new window.
[Acquisition.gov](https://Acquisition.gov)
Aria Label Attached to Link (contains new window keyword):
Description: Shows a link with an ARIA label that includes keywords indicating it will open in a new window.
[Acquisition.gov](https://Acquisition.gov)
Email Link:
Description: Example of an email link.
[IAEOutreach@gsa.gov](mailto:IAEOutreach@gsa.gov)
```
--------------------------------
### Data Display and Binding in SAM Design System Templates
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/table/demos/full/full.component.html
This snippet demonstrates common template syntax for rendering dynamic data, including object properties, function calls, URL generation, and data formatting. It also shows how to display structured data as JSON, and includes surrounding static text that forms part of the template's output structure.
```Template
ID {{ element.id }} Total First {{ element.firstName }} Last {{ element.lastName }} Email [{{ element.email }}](https://beta.sam.gov) Requests {{ element.requests }} {{ getTotalRequests() }} Date {{ element.date | date }} Tags
* {{ tag.label }}
Actions [Edit](#)
Catch Phrase:
{{ element.catchPhrase }}
Job Title:
{{ element.jobTitle }}
* * *
Change number of rows:
5 rows 25 rows 50 rows (HTTP Async) 100 rows
Edit Data:
{{ rowEdit | json }}
```
--------------------------------
### Display Chip Label and Value using Templating
Source: https://github.com/gsa/sam-design-system/blob/master/libs/packages/sam-formly/src/lib/formly-filters/sds-filters.component.html
This snippet shows how to render a chip's label and an associated value, typically used for filter chips. It expects a 'chip' object with a 'label' property and a separate 'value' variable to be available in the template context.
```Templating
{{ chip.label }}: {{ value }}
```
--------------------------------
### Angular Module for Component Registration and Routing
Source: https://github.com/gsa/sam-design-system/blob/master/CONTRIBUTING.md
This TypeScript module (`HeaderModule`) demonstrates how to register a component's demos, define routes for documentation tabs (examples, API, source, template), and integrate external markdown content for opening and closing sections. It uses `raw-loader` to import file contents directly and sets up the routing structure for component documentation.
```TypeScript
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { HeaderBasic } from './demos/basic/header-basic.component';
import { DocumentationExamplesPage } from '../shared/examples-page/examples.component';
import { DocumentationAPIPage } from '../shared/api-page/docs-api.component';
import { DocumentationSourcePage } from '../shared/source-page/source.component';
import { DocumentationTemplatePage } from '../shared/template-page/template.component';
import {
DocumentationComponentsSharedModule,
DocumentationDemoList
} from './../shared/index';
import { ComponentWrapperComponent } from './../../shared/component-wrapper/component-wrapper.component';
import { HeaderBasicModule } from './demos/basic/header-basic.module';
export declare var require: any;
export const opening = require('!!raw-loader!./opening.md'); // load the content of the markdown in to a variable
export const closing = require('!!raw-loader!./closing.md'); // load the content of the markdown in to a variable
const DEMOS = {
basic: {
title: 'SAM Header', // Provide a title for this demo
type: HeaderBasic, // Component to use for this demo
code: require('!!raw-loader!./demos/basic/header-basic.component'), // Source Tab Content
markup: require('!!raw-loader!./demos/basic/header-basic.component.html'), // Template Tab Content
readme: require('!!raw-loader!./demos/basic/readme.md'), // Demo description markdown
path: 'libs/documentation/src/lib/components/header/demos/basic' // Path to demo for the Github link
}
};
export const ROUTES = [
{ path: '', pathMatch: 'full', redirectTo: 'examples' },
{S
path: '',
component: ComponentWrapperComponent,
data: {
readme: {
opening, // Opening section markdown (imported with require above)
closing // Closing section markdown (imported with require above)
},
items: [ // Defines what documentation to display on the API tab, repeats if multiple are specified
{
pkg: 'components', // Package specifies which compodocs to use (/apidocs/components/components.ts)
type: 'components', // Within the compodocs, target the components section
name: 'SdsHeaderComponent' // Show the SdsHeaderComponent object for API information
}
]
},
children: [ // You can omit any tab sections by removing the child routes here
{ path: 'examples', component: DocumentationExamplesPage },
{ path: 'api', component: DocumentationAPIPage },
{ path: 'source', component: DocumentationSourcePage },
{ path: 'template', component: DocumentationTemplatePage }
]
}
];
@NgModule({
imports: [
CommonModule,
DocumentationComponentsSharedModule,
HeaderBasicModule // Import all of your demo modules here (basic, advanced, etc)
]
})
export class HeaderModule {
constructor(demoList: DocumentationDemoList) {
demoList.register('header', DEMOS); // Register the component with the demo list (name must match the route name)
}
}
```
--------------------------------
### Displaying Rich Text Editor Model Value
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-rich-text-editor/formly-rich-text-editor.component.html
An example of how to bind and display the rich text editor's current value, typically used within a templating engine to output the content as a JSON string.
```HTML
Rich Text Editor Value: {{ model.editor | json }}
```
--------------------------------
### Display User Profile Information
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/table/demos/highlight-and-click/highlight.component.html
This template snippet demonstrates how to bind and display various properties of an 'element' object, such as ID, first name, last name, email, requests, and a date. It includes an example of creating a markdown-style link for the email address and applying a date formatting filter to the 'date' property.
```Jinja-like Template
ID {{ element.id }} First {{ element.firstName }} Last {{ element.lastName }} Email [{{ element.email }}](https://beta.sam.gov) Requests {{ element.requests }} Date {{ element.date | date }}
```
--------------------------------
### Render Model as JSON for Labeled Groups
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/autocomplete/autocomplete-grouping/autocomplete-grouping.component.html
Similar to the previous snippet, this example also renders a data model as a JSON string. However, its context is specifically for groups where the names function as labels rather than interactive, selectable elements. This approach is useful for displaying structured data in a read-only or informational capacity within the design system.
```Jinja2
{{ model2 | json }}
```
--------------------------------
### Import Icons into Angular Module
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/utilities/icons/icons-basic/icons-basic.component.html
Before using icons, they must be imported from either `ngx-bootstrap-icons` or `@gsa-sam/ngx-uswds-icons` into the Angular module where your component is declared. This step makes the icon definitions available for selection.
```TypeScript
import { NgxBootstrapIconsModule, square } from 'ngx-bootstrap-icons';
import { add, IconModule } from '@gsa-sam/ngx-uswds-icons';
```
--------------------------------
### Address and Dynamic Data Display Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/tree-table/tree-table-basic/tree-table-basic.component.html
This template snippet combines a static address with dynamic data fields `{{ row.description }}` and `{{ row.year }}`. It's typically used for displaying detailed information related to a specific row or entity.
```Templating
Address 545 S 3rd St Ste 310, Louisville, KY 40404-1936 USA {{ row.description }} {{ row.year }}
```
--------------------------------
### SDS Dialog API Structure Overview
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/dialog/demos/official/dialog-official.component.html
This section outlines the hierarchical structure of the SDS Dialog API documentation, starting with the main API reference and detailing specific modal implementations like the 'Official policy modal'. It indicates where further details on modules, components, properties, and methods would typically be found.
```APIDOC
SDS Dialog API Reference:
Module: SdsDialogModule
Source: '@gsa-sam/components'
Description: (Details not provided in source)
Components:
Official policy modal:
Description: (Details not provided in source)
Properties: (Not provided)
Methods: (Not provided)
```
--------------------------------
### Displaying Element Properties in Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/table/table-expansion/table-expansion.component.html
This snippet illustrates how to access and display different attributes of an `element` object within a template. It shows direct property access, date formatting using a 'date' filter, and creating a hyperlink from an email address. It also demonstrates displaying simple string properties.
```Templating
ID {{ element.id }} First {{ element.firstName }} Last {{ element.lastName }} Email [{{ element.email }}](https://beta.sam.gov) Requests {{ element.requests }} Date {{ element.date | date }}
Catch Phrase:
{{ element.catchPhrase }}
Job Title:
{{ element.jobTitle }}
```
--------------------------------
### Dynamic Row Level Link Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/tree-table/tree-table-basic/tree-table-basic.component.html
A template snippet for generating dynamic links associated with row levels. It uses `{{ level }}` and `{{ row.title }}` for dynamic content and `javascript:void(0)` as a placeholder for the link's action, often used in UI frameworks.
```Templating
[Row Level {{ level }} {{ row.title }}](javascript:void\\(0\\))
```
--------------------------------
### Template Data Interpolation Examples
Source: https://github.com/gsa/sam-design-system/blob/master/libs/packages/sam-formly/src/lib/formly/types/table.html
Illustrates various ways to display data within templates, including direct property access (e.g., `column.label`), accessing properties from a `props` object, and dynamic property access with function calls on an `element` object.
```Template
{{column.label}}
{{props.noDataText}}
{{element[column.property]}} {{column.text}} {{column.textFn(element)}}
```
--------------------------------
### Display Field Label using Templating
Source: https://github.com/gsa/sam-design-system/blob/master/libs/packages/sam-formly/src/lib/formly-filters/sds-filters.component.html
This snippet demonstrates how to access and display a field's label property using a templating engine. It assumes a 'field' object with a 'props' sub-object containing a 'label' property is available in the template context.
```Templating
{{ field.props.label }}
```
--------------------------------
### Pre-17.0.7 Popover HTML Embedding
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/popover/popover-introduction/popover-introduction.component.html
Demonstrates the previous method of embedding HTML content directly into a popover using a simple element reference with a tag. This approach is deprecated in version 17.0.7.
```HTML
Hello, World!
```
--------------------------------
### Display Selected Panel Text in Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/selection-panel/demos/collapsible-panel/collapsible-panel.component.html
This snippet illustrates a common templating pattern to display the 'text' property from a 'selectedPanel' object. It utilizes optional chaining ('?.') to safely access the property, preventing runtime errors if 'selectedPanel' is null or undefined.
```Templating
{{ selectedPanel?.text }}
```
--------------------------------
### Accessing Object Values in SAM Design System Templates
Source: https://github.com/gsa/sam-design-system/blob/master/libs/packages/components/src/lib/selected-result/selected-result.component.html
This snippet demonstrates how to retrieve and display values from an object within the SAM Design System's templating syntax. It shows two common patterns: using a utility function for potentially complex or dynamic property access, and direct property access with a dynamically determined field name.
```Templating
{{ getObjectValue(result, configuration.primaryTextField, i) }}
{{ result\[configuration.secondaryTextField\] }}
```
--------------------------------
### Post-17.0.7 Popover HTML Embedding with ng-template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/popover/popover-introduction/popover-introduction.component.html
Illustrates the new, recommended approach for embedding HTML content into a popover. Content must now be wrapped within an `ng-template` element, which is then referenced by the popover component. This change improves content encapsulation and rendering.
```HTML
Hello, World!
```
--------------------------------
### Configure Min and Max Dates in JavaScript
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-datepicker/demos/daterangev2/datepicker-daterangev2.component.html
This JavaScript snippet demonstrates how to set minimum and maximum date values using `new Date()` objects. These properties are typically used in date pickers or validation logic to restrict user input to a specific date range.
```JavaScript
minDate: new Date(2019, 9, 5),maxDate: new Date(2020, 11, 15),
```
--------------------------------
### Displaying Element Properties and Calling Functions in Angular Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/table/table-custom-footer/table-custom-footer.component.html
This snippet showcases common template expressions for data binding. It demonstrates how to access properties of an 'element' object (e.g., id, firstName, lastName, email, requests, date), how to embed a URL using a property, how to call a global or component method (getTotalRequests()), and how to apply a pipe (date) for formatting.
```Angular Template
ID {{ element.id }} Total First {{ element.firstName }} Last {{ element.lastName }} Email [{{ element.email }}](https://beta.sam.gov) Requests {{ element.requests }} {{ getTotalRequests() }} Date {{ element.date | date }}
```
--------------------------------
### Jinja2 Template for Item ID and Title Display
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/result-list/demos/basic/result-list-basic.component.html
This snippet demonstrates a common templating pattern, likely Jinja2 or a similar engine, used to dynamically display properties of an 'item' object. It's typically used within UI components to render lists or details, showing both an identifier and a descriptive title for each item.
```Jinja2
* ID {{ item.id }} - {{ item.title }}
```
--------------------------------
### Access Angular CLI Help
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
Displays general help information and available commands for the Angular CLI.
```Shell
ng help
```
--------------------------------
### SdsTabsModule API Documentation
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tabs/demos/auto-activate/tabs-auto-activate.component.html
Detailed API documentation for the `SdsTabsModule`, outlining its configurable properties and their effects on tab behavior.
```APIDOC
SdsTabsModule:
Properties:
automaticActivation: boolean
Description: Controls the activation behavior of tabs when navigating with keyboard arrow keys.
Details: By default, tabs are manually activated, requiring 'ENTER' or 'SPACE' to select a tab after focusing it with arrow keys. When `true`, the next tab is automatically selected upon pressing LEFT or RIGHT arrow keys.
Example Usage: [automaticActivation]="true"
```
--------------------------------
### Display Formly Model as JSON
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-autocomplete/demos/tag/autocomplete-tag.component.html
This snippet demonstrates how to render the current state of a Formly model object directly within a template, formatted as a JSON string. This is particularly useful for debugging purposes, allowing developers to inspect the data structure and values held by the form's model in real-time.
```HTML
{{ model | json }}
```
--------------------------------
### Angular Autocomplete Custom Suggestion Template Example
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/autocomplete/demos/customtemplate/autocomplete-customtemplate.component.html
Provides an example of an Angular template expression used within a custom suggestion template. This expression demonstrates how to access and display properties of the `item` object, such as `name` and `subtext`, for each autocomplete suggestion.
```HTML
{{ item['name'] + ': ' + item['subtext'] }}
```
--------------------------------
### Run Automated Release Process with npm Helper Scripts
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
These helper scripts automate a significant portion of the release workflow, including versioning, Git commits, tagging, pushing to GitHub, and generating release notes. They should be executed on the master branch, and users are advised to exercise caution due to their comprehensive nature.
```npm
npm run release:patch
```
```npm
npm run release:minor
```
```npm
npm run release:major
```
--------------------------------
### Build Angular Project
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
Compiles the Angular application into deployable build artifacts, stored in the `dist/` directory. The `--prod` flag optimizes the build for production environments.
```Shell
ng build --project=myapp
ng build --project=myapp --prod
```
--------------------------------
### Angular: Interpolate Item Title
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/result-list/demos/template/result-list-template.component.html
A basic example of Angular interpolation to display the `title` property of an `item` object. This snippet shows the simplest form of data binding to render text content dynamically.
```Angular
{{ item.title }}
```
--------------------------------
### Render Model as JSON for Selectable Groups
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/autocomplete/autocomplete-grouping/autocomplete-grouping.component.html
This snippet demonstrates how to output a data model directly as a JSON string within a template. This is typically used when the entire model's structure and content need to be exposed, for instance, for client-side JavaScript processing or debugging. The context here implies that the rendered data pertains to groups where names are selectable.
```Jinja2
{{ model | json }}
```
--------------------------------
### Displaying Icons with usa-icon Component
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/icons/demos/basic/icons-basic.component.html
This example shows how to embed an icon in an Angular template using the `usa-icon` component. The `icon` input specifies the desired icon, and `size` controls its display dimensions.
```HTML
```
--------------------------------
### Selection Panel Component API Reference
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/selection-panel/demos/basic/basic-selection-panel.component.html
Defines the input model, properties, and output events for the Selection Panel component, detailing its behavior in different selection modes and how navigation is handled.
```APIDOC
SelectionPanelComponent API:
Inputs:
- model: SelectionPanelModel
Description: Base input requirements for the selection panel component.
Extends: SideNavigationModel
Properties:
- selectionMode: string ('SELECTION' | 'NAVIGATION')
Default: 'NAVIGATION'
Description: Controls visibility of children and internal route navigation.
- 'SELECTION': Children of navigation links not shown, no internal route navigation.
- 'NAVIGATION': Children of navigation links shown, allows internal route navigation.
- navigateOnClick: boolean
Description: Toggles route navigation when a panel item is selected.
Outputs:
- panelSelected: (NavigationLink)
Description: Fired anytime a navigation item is selected, providing the selected NavigationLink.
```
--------------------------------
### sdsTooltip Directive API Reference
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tooltip-popover/demos/tooltip/tooltip-basic.component.html
Detailed API documentation for the sdsTooltip directive, outlining its purpose, available inputs, default values, and accepted options for positioning.
```APIDOC
sdsTooltip Directive:
Description: When applied to an element, a tooltip will appear when the element is hovered over.
Inputs:
- sdsTooltip (string | ElementRef):
Description: The contents of the tooltip. This can be set by passing either a string or an element reference.
- position (string):
Description: Controls the tooltip's display position relative to the element.
Default: 'top'
Valid Values: 'top', 'right', 'bottom', 'left'
```
--------------------------------
### Search Component API Reference
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/search/search-overview/search-overview.component.html
Details the configurable properties and emitted events for the main search input component.
```APIDOC
Outputs:
(submit): Emits when the user clicks submit. The value of the event contains the current state of the model.
Properties:
placeholder: string - Text to serve as a placeholder in search input.
isSuffixSearchIcon: boolean - Used for suffixing the search icon.
size: string - Size of the search, defaults to 'small'.
inputClass: string - String of classes to be applied to search input.
parentSelector: string - CSS selector of the element containing search component.
dropdown: object - Dropdown settings object (see 'Search Dropdown Component Properties' for details).
```
--------------------------------
### Configure Minimum and Maximum Dates for Validation
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/formly/formly-datepicker/formly-datepicker-validation/formly-datepicker-validation.component.html
Examples demonstrating how to set specific minimum and maximum dates using JavaScript Date objects for date input validation or picker range limits.
```JavaScript
minDate: new Date(2019, 6, 5)
```
```JavaScript
maxDate: new Date(2020, 11, 25)
```
```JavaScript
minDate: new Date(2019, 9, 5),maxDate: new Date(2020, 10, 15),
```
--------------------------------
### Build and Publish SamDesignSystem Libraries to npm
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
This script identifies all publishable libraries within the angular.json configuration, builds them, creates tarballs, and then publishes them to npmjs. It is critical to ensure the local branch is fully synchronized with the approved release code before executing this command.
```npm
npm run publish:libs
```
```npm
npm run publish:libs -- --dry-run
```
--------------------------------
### Configure Autocomplete Minimum Character Count in Formly
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/formly/formly-autocomplete/formly-autocomplete-count/formly-autocomplete-count.component.html
This setting is used to enable and define the minimum number of characters required before an autocomplete search is triggered within a Formly form. In this example, a minimum of 3 characters is set.
```JavaScript
this.settings.minimumCharacterCountSearch = 3
```
--------------------------------
### Autocomplete with Checkboxes Data Model Rendering
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/autocomplete/autocomplete-checkbox/autocomplete-checkbox.component.html
This snippet shows the templating expression used to render the 'model' data object as a JSON string. This data likely defines the configuration and options for an autocomplete component that includes checkboxes.
```Jinja2
{{ model | json }}
```
--------------------------------
### SdsTabsModule API Reference: tabClass Input
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tabs/demos/styling/tabs-styling.component.html
Detailed API documentation for the `tabClass` input property of the `SdsTabsModule`, explaining its purpose, type, and how it enables custom styling of tab headers and content panels through specific CSS selectors.
```APIDOC
SdsTabsModule:
Inputs:
tabClass: string
Description: A custom CSS class to apply to the tab container.
Usage: [tabClass]="'your-custom-class'"
Customization:
- Tab Headers: Define '.sds-tabs__item' as a child of the custom class (e.g., '.your-custom-class .sds-tabs__item').
- Content Panel: Define '.sds-tabs__content' as a sibling (using '+') of the custom class (e.g., '.your-custom-class + .sds-tabs__content').
```
--------------------------------
### Dynamic Step Text and Placeholder Link Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-stepper/demos/advanced/custom-stepper.component.html
This snippet illustrates the use of a templating variable to display dynamic step text within an HTML link. The `javascript:void(0);` URL is used as a placeholder, indicating that the link's behavior would typically be handled by client-side JavaScript.
```HTML
{{ step.text }} [{{ step.text }}](javascript:void\(0\);)
```
--------------------------------
### Hide Optional Text Configuration
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/templateoptions/demos/hideOptional/templateoption-hideOptional.component.html
This configuration property is used to suppress the display of the '(optional)' text label, typically associated with form fields or input elements, when it's not desired to explicitly mark them as optional.
```Configuration
hideOptional: true
```
--------------------------------
### SAM Design System Configuration Files
Source: https://github.com/gsa/sam-design-system/blob/master/CONTRIBUTING.md
This section enumerates and briefly describes key configuration files used across the SAM Design System project. These files manage various aspects of the development environment, including Angular CLI settings, GitHub pull request approvals, testing frameworks (Jest, Karma), Nx monorepo configuration, package dependencies, and TypeScript compilation and linting rules.
```APIDOC
Configuration:
angular.json: Angular CLI configuration
CODEOWNERS: Github pull request approvers
jest.conf.js: JEST testing framework configuration
karma.conf.js: Karma test runner framework configuration
nx.json: NX Workspace monorepo configuration and dependency tagging
package-lock.json: Pre-processsed project dependencies
package.json: Project version, dependencies, and scripts
tsconfig.json: Typescript configuration
tslint.json: Typescript linter configuration
```
--------------------------------
### Import SdsTabsModule for Angular Applications
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tabs/demos/dynamic-tabs/dynamic-tabs.component.html
This snippet demonstrates the required import statement to integrate the SdsTabsModule from the @gsa-sam/components library into an Angular project. This module provides core functionality for building and managing tabbed interfaces.
```TypeScript
import { SdsTabsModule } from '@gsa-sam/components';
```
--------------------------------
### Import SdsTabsModule
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tabs/demos/auto-activate/tabs-auto-activate.component.html
Imports the `SdsTabsModule` from the `@gsa-sam/components` library, making it available for use in Angular applications.
```TypeScript
import { SdsTabsModule } from '@gsa-sam/components';
```
--------------------------------
### Execute Angular Unit Tests
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
Runs the unit tests for the Angular application using Karma.
```Shell
ng test
```
--------------------------------
### Define Autocomplete Group Child Property (JavaScript/TypeScript)
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/autocomplete/demos/selectgroup/autocomplete-selectgroup.component.html
Specifies the `groupByChild` property name, which indicates the field within each data item that should be used to determine its group affiliation. In this example, 'elements' is used as the child property name for grouping.
```JavaScript
this.settings.groupByChild = 'elements';
```
--------------------------------
### Display Icons in Angular Template
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/storybook/utilities/icons/icons-basic/icons-basic.component.html
Once icons are configured in the module, they can be displayed in your component's template using the `usa-icon` component. The `icon` input property should be set to the string name of the selected icon, and `size` can be used to control its display size.
```HTML
```
--------------------------------
### Link Angular Projects for Local Development
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
A sequence of commands to link a local Angular library project to a separate application. This allows for real-time development and testing of the library within the consuming application without publishing.
```Shell
ng build project-name
cd dist/libs/project-name
npm link
cd ../../../
ng build --watch
npm link @gsa-sam/project-name
```
--------------------------------
### Push Local Git Changes and Tags to Remote Repository
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
These commands are essential for synchronizing local version updates and newly created Git tags with the remote GitHub repository. They must be run manually after the npm version command to ensure the remote is up-to-date.
```Git
git push origin master
```
```Git
git push --tags
```
--------------------------------
### Templating for User Data Display
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/table/demos/basic/basic.component.html
This template snippet illustrates how to render dynamic user data, such as ID, first name, last name, email, requests, and a formatted date. It showcases basic variable interpolation, a URL link for the email, and a date formatting filter, typical in front-end templating engines like Jinja2 or Nunjucks.
```Templating
ID {{ element.id }} First {{ element.firstName }} Last {{ element.lastName }} Email [{{ element.email }}](https://beta.sam.gov) Requests {{ element.requests }} Date {{ element.date | date }}
```
--------------------------------
### sdsPopover Directive API Reference
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tooltip-popover/demos/basic/popup-basic.component.html
Detailed API specification for the `sdsPopover` directive, outlining its purpose, configurable inputs (`sdsPopoverTitle`, `position`), their types, descriptions, and valid values.
```APIDOC
sdsPopover Directive:
Description: Applies a popover to an element that appears when the element is clicked.
Inputs:
sdsPopoverTitle:
Type: string | ElementReference
Description: The title of the popover. Not required; if omitted, the popover renders without a divider.
(Implicit Content Input):
Type: string | ElementReference
Description: The main content of the popover, passed directly to the directive.
position:
Type: string
Description: Controls the placement of the popover relative to the element.
Default: "top"
Valid Values: "top", "right", "bottom", "left"
```
--------------------------------
### Display JSON Model in Templating Language
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-datepicker/demos/daterange/datepicker-daterange.component.html
This templating snippet shows how to conditionally render a `model` variable as a JSON string. It checks if the `model` variable exists and, if so, applies a `json` filter to pretty-print its content, otherwise it renders an empty string.
```Templating
{{ model ? (model | json) : '' }}
```
--------------------------------
### Configure Min/Max Dates in JavaScript
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-datepicker/demos/daterange/datepicker-daterange.component.html
This snippet demonstrates how to set minimum and maximum date values using JavaScript `Date` objects for date validation purposes. The `minDate` and `maxDate` properties are used to define the allowed date range for an input.
```JavaScript
minDate: new Date(2019, 9, 5),maxDate: new Date(2020, 11, 15),
```
--------------------------------
### Generate Angular Components and Other Schematics
Source: https://github.com/gsa/sam-design-system/blob/master/README.md
Commands to scaffold new Angular components, directives, pipes, services, classes, guards, interfaces, enums, or modules using the Angular CLI.
```Shell
ng generate component component-name --project=myapp
ng generate directive|pipe|service|class|guard|interface|enum|module
```
--------------------------------
### Displaying Formly Model as JSON
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/formly-autocomplete/demos/disable/autocomplete-disable.component.html
This example shows how to display the current state of the Formly model in a human-readable JSON format directly within an Angular template. This is particularly useful for debugging purposes, allowing developers to inspect the data bound to the form fields.
```Angular Template
{{ model | json }}
```
--------------------------------
### Import SdsTabsModule for Tabs Component
Source: https://github.com/gsa/sam-design-system/blob/master/libs/documentation/src/lib/components/tabs/demos/basic/tabs-basic.component.html
This snippet demonstrates how to import the `SdsTabsModule` from the `@gsa-sam/components` library. This module is essential for utilizing the Tabs component within an Angular application, providing the necessary components and directives for creating tabbed navigation.
```TypeScript
import { SdsTabsModule } from '@gsa-sam/components';
```