Noisy Pterodactyl Melodies

    @n8d/htwoo-react
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    HTWOO ReactJS Components

    HTWOO ReactJS is an open source alternative for Microsoft's various implementations of their Fluent UI Web Design system. This library consists of flexible ReactJS components based on the HTWOO UI library. For a complete listing please see HTWOO Core Style Guide.

    Complete documentation of the HTWOO ReactJS components

    100% Fluent Design DOM manipulation free license

    How To Use

    Note: This component library is currently under development and will most likely continue to make improvements that could likely bring about breaking changes. Please feel free to submit your enhancement ideas and feedback to the issues list so that we can try to address them.

    Initialize library in Microsoft SharePoint Framework (SPFx)

    1. Install package in your solution.

      This package has a peer dependency on the correspoinding version of @n8d/htwoo-core so that will be added automatically for you.

      npm i @n8d/htwoo-react --save
    2. Add a reference to the style.prod.scss file in your solutions root .scss file. Put the reference inside of the webparts base class so that the styles are scoped to the instance of this webpart:

      Note: The import is wrapped in :global so that the class names will not be modified with a namespace.

      .myWebPartRoot{
        :global {
          @import 'node_modules/@n8d/htwoo-core/lib/sass/style.prod';
        }
      }

      then in your root component's top level HTML element add a reference to that base class. This will make sure that when your project builds, the styles will be included. For example:

      public render(): React.ReactElement<IHtwooReactDemoProps> {
        try {
          return (
            <div className={styles.myWebPartRoot}>
              Hello World
            </div>
          );
        } catch (err) {
          console.error(`${this.LOG_SOURCE} (render) - ${err}`);
          return null;
        }
      }
      
    3. To initilize the basic SVG icons add the following line to your components main ts file's onInit method:

      import { symset } from '@n8d/htwoo-react/SymbolSet';
      
      public async onInit(): Promise<void> {
        // Initialize Icons Symbol Set
        await symset.initSymbols();
      }

      Alternately you can load your own icon symbol set by passing the path into the initSymbols method:

      This will load both the default hoo-icons as well as whatever icons are in your referenced file.

      import { symset } from '@n8d/htwoo-react/SymbolSet';
      
      public async onInit(): Promise<void> {
        // Initialize Icons Symbol Set with Custom Symbol File
        const symbolSetFile: string = require("./images/icons.svg");
        await symset.initSymbols(symbolSetFile);
      }

      A SVG symbol file will look similar to the following:

      <svg aria-hidden="true" style="position: absolute; width: 0; height: 0; overflow: hidden;" version="1.1"
        xmlns="http://www.w3.org/2000/svg"
        xmlns:xlink="http://www.w3.org/1999/xlink">
        <defs>
            <symbol id="icon-arrow-left" viewBox="0 0 32 32">
                <path d="M22.547 31.953l-15.969-15.953 15.969-15.953 1.406 1.406-14.531 14.547 14.531 14.547-1.406 1.406z"></path>
            </symbol>
        </defs>
      </svg>

      If you are looking to load icons from the @n8d\htwoo-icons library you can install the package and then import them by referencing the svg file in the node_modules folder.

      import { symset } from '@n8d/htwoo-react/SymbolSet';
      
      public async onInit(): Promise<void> {
        // Initialize Icons Symbol Set with HTWOO-Icons
        const fuireg: string = require("@n8d/htwoo-icons/fluent-ui-regular/fluent-ui-regular.svg");
        await symset.initSymbols(fuireg);
      }

      To use the icons in this file, you will reference them by the individual icon's id value, which in the SVG file sample above is icon-arrow-left. Here's an example of using an icon in the HOOAction component

      <HOOAction iconName="hoo-icon-plus" label="Action Button" type={HOOActionType.Action}/>
    4. (Optional) Add theme support to your SPFx project

      a. Modify your components manifest and add supportsThemeVariants which allows any of the hTWOo components to render properly in colored SharePoint section.

      { 
        //...
        "supportsThemeVariants": true,
        // ...
      }

      b. Add the following helper code to your components main ts file's onInit method which initializes the CSS Variables to support themes. Make sure to add the import and the private _spfxThemes variable:

      import { ThemeProvider } from '@microsoft/sp-component-base';
      import { SPFxThemes, ISPFxThemes } from '@n8d/htwoo-react/SPFxThemes';
      
      private _spfxThemes: ISPFxThemes = new SPFxThemes();
      
      public async onInit(): Promise<void> {
        // Consume the new ThemeProvider service
        const microsoftTeams = this.context.sdks?.microsoftTeams;
        const themeProvider = this.context.serviceScope.consume(ThemeProvider.serviceKey);
        this._spfxThemes.initThemeHandler(this.domElement, themeProvider, microsoftTeams);
      
        // If no ThemeProvider service, do not include property which will use page context
        this._spfxThemes.initThemeHandler(document.body);
      }

      There are two other alterivatives to adding theme support, for more information please check out the SPFxThemes Class documentation.

    5. Import the HTWOO component that you want to use into your own projects components. All components are selectively importable from the /lib/ folder. We will be working on fully documenting all components and their implementation soon.

    HTWOO Base Concept

    hTWOo style guide, documentation and building platform is based on patternlab.io. To allow the most flexible implementation of designs and design pattern it follows the Atomic Design Methodology coined by Brad Frost around 2012 / 2013.

    We're tasked with making interfaces for more users in more contexts using more browsers on more devices with more screen sizes and more capabilities than ever before. That's a daunting task indeed. Thankfully, design systems are here to help. - Brad Frost

    Engage

    Follow us on Twitter @htwooui.

    Maintainer: Stefan Bauer (N8D), Julie Turner

    Contributor: You ❤️

    Install

    npm i @n8d/htwoo-react

    DownloadsWeekly Downloads

    38

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    673 kB

    Total Files

    400

    Last publish

    Collaborators

    • stfbauer