sap/fundamental-ngx

Fundamental Library for Angular is SAP Design System Angular component library

Fundamental Library for Angular

Content

• 1. Description
• 2. Requirements
• 3. Known Issues
• 4. Support
• 5. Contributing
• 6. License
• 7. Similar Projects

1. Description

The Fundamental Library for Angular is an SAP Design System Angular component library used to build modern product user experiences with the SAP look and feel.

This repository contains 2 libraries(npm packages),

• @fundamental-ngx/core: The Fundamental-NGX core provides base angular implementation of Fundamental Library Styles to offer developers a rich set of components they can use when building angular applications. Fundamental-ngx core angular components provides the end developer with some degree of flexibility as most of the components allow finer customization directly on the HTML template level.

• @fundamental-ngx/platform: The Fundamental-NGX platform is built on top of the core to both enhance existing functionality with additional features which are driven by application requirements and to provide higher abstraction for the components by hiding most of the internal implementation details which boosts productivity.

2. Requirements

To download and use Fundamental Library for Angular, you will first need to install the node package manager.

Fundamental Library for Angular is intended for use with Angular 15 or newer.

Prior knowledge of Angular is recommended, to use the fundamental-ngx library.

3. Known Issues

• Please see Issues.
• Contribution Known Issues

4. Support

If you encounter an issue, you can create a ticket.

Angular Versions Support: Our versions offer Angular support. More information can be found here.

• Features and enhancements are developed to the latest version of fundamental-ngx.

• Bugfixes can be downported to the latest ngx version, which is compiled with the second last Angular version.

5. Contributing

If you want to contribute, please check the CONTRIBUTING.md documentation for contribution guidelines. Please follow the Angular commit message guidelines.

Check out the NEW_COMPONENT.md guide on building a new component for the library and creating the necessary documentation for your new component.

Similar Projects

7. Similar Projects

Fundamental-react - React implementation of Fundamental Library Styles

Fundamental-vue - Vue implementation of Fundamental Library Styles

fundamental-ngx's Issues

Build and deploy for both the docs site and the fd-ngx library should be npm scripts

Is this a bug, enhancement, or feature request?

Enhancement

Briefly describe your proposal

Currently there is no clear documentation or single build step for building/deploying the documentation website or the build script. These should be npm scripts, and if named properly should be self-documenting for anyone with a decent understanding of npm/ng cli etc.

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

Set up our documentation on sap.github.io GitHub Pages

Is this a bug, enhancement, or feature request?

enhancement

Briefly describe your proposal

We should deploy the documentation application at sap.github.io/fundamental-ngx, like how Fundamental has done here: https://sap.github.io/fundamental/

Is there anything else we should know?

This may help:
https://alligator.io/angular/deploying-angular-app-github-pages/

"how to" create a new component blog

how to make a fundamental-ngx application in '30 seconds' video

Code formatting using Prettier JS

Add prettier js to the library and have it run before commits

Expose functions for setting selected tab by ID

Is this a bug, enhancement, or feature request?

Feature request

Briefly describe your proposal

Users should be able to set an ID on tabs in a tab list, and call a function setSelectedTab(tabId) to select it programmatically. We should also expose a (tabChange) event handler.

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

Breadcrumb item text should not be @Input() but ng-content

Is this a bug, enhancement, or feature request?

Enhancement

Briefly describe your proposal

Breadcrumb text should be provided between tags, not as an @input() property.

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

make fundamental-ngx CDN

Restructure workspace to facilitate Angular Package Format and generate npm package

In order to consume this library we need to put in a build process that is capable to transpile the components into a distribution-ready npm package. This has been a challenge in the past, but since angular CLI 6 this is standardized. It is recommended to update the project to angular 6 first, and then restructure the project slightly and take advantage of the build processes of ng-packagr.

Documentation should also import the component library directly from the library source rather than depending on builds

Create github guidelines for PR

Similar to the creation of Issue guidelines (#18) we could setup a template for PRs; Github provides a template for PRs so project owners can dictate the rules for PRs. We should create a file PULL_REQUEST_TEMPLATE.md in the .github folder. This contributor will see the content of this template contents automatically when they create a PR.

See https://help.github.com/articles/about-issue-and-pull-request-templates/.

add Jekyll SEO tag to improve discoverability for the documentation GitHub Pages site

Is this a bug, enhancement, or feature request?

Enhancement

Briefly describe your proposal

We should add this Jekyll SEO tag to help ensure the documentation will show up in searches etc.
Relevant documentation:
https://help.github.com/articles/search-engine-optimization-for-github-pages/
https://blog.github.com/2016-05-10-better-discoverability-for-github-pages-sites/

Docs: add margins between components

Is this a bug, enhancement, or feature request?

enhancement

Briefly describe your proposal

Some of the components in the documentations are squished right next to each other. Add margins like they have on the Fundamental UI docs: https://sap.github.io/fundamental/components/button.html

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

Update to newer version of fundamental-ui

Based on the vulnerabilities introduced with #12 we need to update to newer version of fundamental-UI as soon as they're fixed.

See SAP/fundamental#478

implement side navigation https://sap.github.io/fundamental/components/side-navigation.html

Breadcrumb links should be styled on component, not docs

Is this a bug, enhancement, or feature request?

Bug

Briefly describe your proposal

The breadcrumb links are styled on the docs rather than the components themselves, so someone using the library doesn't get properly styled breadcrumb links

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.2-beta

Schema enhancements

While we move to angular 6 (#12) we updated typescript along the way. This gives a lot of the following errors, since the Schema is not used correctly.

Types of property 'properties' are incompatible.

We haven't fixed this with the upgrade since, that needs to be done in this ticket. Instead we removed the Schema model and used any type.

"how to" create a new component video

• - review the documentation for creating a new component
• - record a video

playground - type dropdown - missing label for default type

Several components have properties such as "size" that can be explicitly set, and if not they're not set, they fall back to a default value. The playground displays an empty string for these options, it should say "default"

Modal service should return modal ref

Is this a bug, enhancement, or feature request?

Enhancement

Briefly describe your proposal

Currently the fundamental-ngx modal service isn't returning ngb's modal ref. This is needed to handle the result of the modal

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

Dropdown (blur) causes strange functionality

Briefly describe your proposal

Using (blur) to close the dropdown causes some undesirable effects. If the user clicks and holds one of the selectable options (rather than a quick click), the dropdown perceives this as a blur event and closes the dropdown, and the option the user clicks on does not register as a click.

Also, clicking the main button on an expanded dropdown should close it.

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

Pagination component has a couple of flaws

Refactor:

• align with standard angular component (naming conventions)
• separate out the html and (s)css
• move logic from component to service

Fix (happens in playground):

• fix empty currentPage (throws error, could default to 1)
• fix empty itemsPerPage (results in Infinity length).
• fix empty totalItems (throws error)

Documentation:

• reuse hard coded model in the

   tag

• bind to the data.properties instead

Pagination calculation wrong

As provided by deno:

if i set totalItems to 10, itemsPerPage to 6, and currentPage to 1 - you can still see 3 available pages

Remove JSON data from playground

implement form components https://sap.github.io/fundamental/components/form.html

Disabled tab in TabListComponent can still be selected

Create guidelines for issues

Project maintainers can add an ISSUE_TEMPLATE.md file for issues to projects, helping contributors share the right details at the start of a thread. I think we should initially not make the template to strict, but as we move forward we might want to put additional rules in.

Examples can be seen at existing (larger) projects, i.e. https://github.com/angular/angular/issues/new or https://github.com/angular/material2/issues/new. Having a small template at least gives a good impression imho.

See https://help.github.com/articles/about-issue-and-pull-request-templates/ for more info.

Create contributor guidelines

To help project contributors do good work, we can add a file with contribution guidelines to your project repository's root, docs, or .github folder. Then, whenever someone opens a pull request or creates an issue, they will see a link to that file.

Since we need to maintain multiple github administration files I'd recommend to create a CONTRIBUTING.md file inside a .github folder.

See https://help.github.com/articles/setting-guidelines-for-repository-contributors/ for more info.

Provide release or changelog automatically

We need to maintain a changelog or detailed release notes in order to inform the community about changes in the project. Several open source projects do this automatically based on a third-party package (such as conventional-changelog) and commit conventions.

It is recommended to figure this out early in the project so that we can start putting requried commit conventions in place.

Breadcrumb links should be <a>, not <span>

Is this a bug, enhancement, or feature request?

Bug

Briefly describe your proposal

Breadcrumb links are not properly styled because they are spans when they should be links.

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.2-beta

setup an open slack channel for help, questions, advices

sap-fundamental-ngx-help

Refactor components

I'd prefer to use external html and scss so that we have a cleaner code base.

I'd also perfer to stick to naming conventions so it's easier to find files in the workspace, i.e.:

• alert.component.ts
• alert.component.html
• alert.component.scss

Using the Component postfix for components will also help to better separate out components and other entities, such as interfaces. If you like to create an interface for a component, you'd like to reserve the entity name (i.e. Pagination) for the interface, where as the component should have a more specific name (i.e. PaginationComponent).

Add e2e tests (to be ran manually while we wait for CI)

Is this a bug, enhancement, or feature request?

Enhancement

Briefly describe your proposal

The components are almost entirely untested now... we should have some e2e tests that we can run manually before merging pull requests. In the future we'll have CI that can handle the tests but for now, manual tests won't hurt

What versions of Angular and Fundamental NGX? (If this is a feature request, use current version)

Angular 6.0.0, fundamental-ngx 0.0.1-beta

Drag-and-Drop for tree/table

Rows and columns should be rearrangeable via drag and drop. When a row is moved, it should fire an event with the object and row index attached.

create an online tool for sharing, running code

• research for existing(open source) one that we can re-use

• maybe we can think how to embed it in the site so we can use it for the code examples.

create a fundamental-ngx "hello world" video

Syntax highlighting on code examples

The Fundamental site is using highlight.js to handle this, we should try to do the same

migrate to angular 6

Wrong pagination calculation

Whenever the number of pages is just 1 more then the min number of pages to show (3), then we get:
1 2 3 ... 4

This is not right. It should be:

1 2 3 4

or 1 2 ... 4

When, with the same data, page 4 is selected, we end up with:
1 ... 2 3 4

When we 60 pages, and 10 items per page, we also frequently end up with 2 dots sections while, i.e.
1 ... 3 4 5 ... 6

Specify correct license in package.json

The license is not represented in the package.json. The license should be specified in package.json so that people know how they are permitted to use the software, and any restrictions we place on it.

The package.json provides a license key that can be used. That can either hold a license type (i.e. MIT) or a short description with a reference to a file at the root. See https://docs.npmjs.com/files/package.json for more info.

explore fundamental-ngx CLI commands

include the fui components styling separately in each component

Currently we are including the whole Fundamental UI library. To help modularize our components, each component should import only the relevant CSS from the Fundamental UI library

fundamental-ngx website - apply similar skin as fun-ui

• remove the left-right gutter
• add top banner
• add search input
• ask Manu to design a landing page

inline help - text goes beyond the visible area

On the Fundamental UI website, inline help hovers above their menus but in our app, it goes behind the menus. Check z-index etc. On the Fundamental website the text/inline help does not wrap if the help goes off screen/out of the browser window so I'm not sure there's anything we can do there

alert

• interactive labels
• playground - dropdown text is cut

dropdown enhancements

• add blur event (close)
• use focus rather then click (so we can tab into it)
• use aria-disabled instead of disabled
• use escape to close dropdown

Button group component issues

• the UI is broken if we mix the size of the buttons within one group so i guess the size could be part of the group. It will avoid repetition as well
• can't we have only 1 directive for the buttons type and it can be set on the group level instead of the current repetition on each button?

table features - potential enhancements

Table/list potential features:
CORE
Prio 1

• craft a stable API
• support images in addition to text/links
• sorting/filtering functionality
• pagination (expose items per page field)
• selection modes (no selection, single row selection, multiple rows selection)
• show/hide columns
• table toolbar buttons
• one-click actions (including more menu)
• load on scroll end
• responsiveness

Prio 2

• grouping rows
• drag and drop
• adjustable column width
• infinite scrolling
• export

Prio 3

• edit mode
• fix columns(left/right); fix rows(bottom/top); sticky headers
• options for resizing table height
• header columns options (wrapping description)

Platform:

• personalization
• meta-data driven columns (CRUD)

Code isn't highlighting properly in every example

Is this a bug, enhancement, or feature request?

Bug

Briefly describe your proposal

Some of the code snippets aren't highlighting properly, need to investigate why

If this is a bug, please provide steps for reproducing it

Identifier, inline help, input group, list, and usage pages are not displaying the snippets with proper highlighting

mega menu component issue

the menu should appear upon a click/hover and not open by default - similar like the 1 level menu and dropdown

Update to newer version of Karma

Based on the vulnerabilities introduced with #12 we need to update to newer version of karma as soon as they're fixed.

See karma-runner/karma#2994.