microsoft / fluentui-react-native

A react-native component library that implements the Fluent Design System.

FluentUI React Native

FluentUI React Native is a javascript component library that provides developers with controls that are part of the Fluent Design System. These controls are built on React Native and fully customizable.

FluentUI React Native is still in the alpha stages of development for both the components and the repo. We encourage anyone who is interested in getting an early glimpse of our plans to download and use our components, but please note that you may hit bumps along the way. Please leave us feedback or file issues if you run into bumps, and we will continue to improve the quality of the repo.

Development status on each platform:

Windows	macOS	iOS	Android
Alpha (in progress)	Alpha (in progress)	Alpha (in progress)	Alpha (in progress)

Getting Started

If you have an existing React Native project, it's easy to begin using FluentUI React Native. If you need to setup a new React Native project, please see the React Native Windows Getting Started documentation.

Prerequisites

• Standard React Native dependencies
• Node.js
• Setting up your React Native Development Environment

Create New React Native project (if needed)

1. Follow the instructions on the React Native Windows Getting Started documentation to create a React Native project.

2. Navigate to the root folder of your project, and use npm to install the package:

 npm i @fluentui/react-native

3. After successful installation, you can test the package by importing components at the top of your app's entry file, e.g. App.js:

import { Checkbox } from '@fluentui/react-native';

4. After importing the @fluentui/react-native package, you can use components such as Text and Checkbox in your JSX.

// In App.js in a new project
import React from 'react';
import { View, Text } from 'react-native';
import { CheckboxV1 as Checkbox } from '@fluentui/react-native';
function HelloWorldApp() {
  return (
    <View
      style={{
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
      }}
    >
      <Text>Hello, world!</Text>
      <Checkbox label="Hello World Checkbox" />
    </View>
  );
}
export default HelloWorldApp;

If you run into an error that says pragma and pragmaFrag cannot be set when runtime is automatic, you can try switching to classic runtime.

Documentation

Components and Controls

Our component documentation can be found in SPEC.md files for each component. The current list can be found in our Wiki's sidebar. They will be uploaded to a website at a future time.

Expanding Component documentation

Our SPEC.md files should reflect the current state of controls that have established the v1 set of properties on any one platform.

Since the FluentUI React Native controls are cross-platform, but represented by a single page, it's important to distinguish platform differences and limitations. Examples include:

• If the component is not available on all supported platforms.
• If the component has properties not available on all supported platforms.
• If the component has limited support for a given property on any supported platforms.
• If the component has distinguishable behavior on a supported platform that must be minded while used.

Theming framework

Documentation for Theming can be found in our docs file, or for more in depth documentation, along side the implementation.

• Theming Overview
• StyleSheets
• Customizing Theme Settings
• Theme Reference
• Tokens
• Slots
• Customize and Compose

Developing in the repo

Yarn + Lage

This repo is set up as a monorepo using Yarn workspaces. To install yarn, please follow instructions in the Yarn documentation.

For running tasks the repo has switched to using Lage for task running. The primary tasks that can be executed at the root are:

• yarn build - does the typescript build for all packages in the repository
• yarn test - will build, lint, and run any applicable tests on all packages in the repo
• yarn bundle - will bundle all packages in the repo
• yarn buildci - will build, lint, run tests, and bundle everything in the repo

Note that Lage uses caching to avoid redundant steps and has very minimal output. To avoid caching add --no-cache as a command line argument. Similarly adding --verbose will give more detailed output.

Setup your development environment

To start developing in the repository you can:

1. git clone https://github.com/microsoft/fluentui-react-native.git
2. cd fluentui-react-native
3. yarn
4. yarn build

After a successful yarn build, you can explore FluentUI Tester, our demo application to play with each of the controls. To run FluentUI Tester, please follow instructions in the FluentUI Tester readme.

Note: If your repo is located on either your Desktop or Documents folder, you may encounter the error: "Watchman error... Operation not permitted". Clone it in a different directory to avoid Watchman permission issues.

Prettier

This repo is set up to run Prettier. To run Prettier in fix mode on the repo, run yarn prettier-fix at the root of the Repo.

If you are using VSCode as your editor, you can configure it to run Prettier on save. Prettier is a recommended extension for the repo. You can configure it to run by:

1. Installing the Prettier extension for VSCode
2. Going to Settings > Text Editor > Formatting > Check Format On Save

Contributing

Please visit our contribution guide for more information on contributing to this repo.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

fluentui-react-native's Issues

FocusTrapZone documentation lacks API, usage information

The FocusTrapZone control needs better documentation added to its FocusTrapZone.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Create Demo app to include in readme/getting started instructions

The library needs a demo app to include in the readme/getting started instructions. The purpose of this demo app is to give folks a quick way to download and use our package in a prepackaged environment, for people that don't have an existing react-native app to add our package to. Examples:

• https://developer.microsoft.com/en-us/fluentui#/get-started#option-1-quick-start
• https://github.com/microsoft/fluentui-apple/blob/master/ios/README.md#demo-app

Move react-native-uifabric here (win32 controls)

We have a few win32 components in another repo. This issue just tracks moving them here.

Add a Size Auditor to CI Loop

A size auditor to check against bundle size change (as fabric-react does) would be really nice to have.

Themed StyleSheets for primitives

We need an easy API for consumers of primitive components to create StyleSheets that can reference theme values and regenerate in response to theme changes.

Clean up peer dependencies to use semantic versioning

We should make a pass through the various packages to ensure we are using references such as "react-native": "^0.60" rather than specific versions. This should be done for everything in the repo.

Document all the things

I just added a bunch of stuff around the Native Module, Theme Provider, and hooks for the Theme Context.

It'd be good to go back and do a pass at documenting everything.

API Documentation

With a PR our for #24, I'm adding an issue to track documentation work. It would be nice to have a documentation generation system. The API-extractor docs note that for simple cases using the api-documenter package (https://www.npmjs.com/package/@microsoft/api-documenter) may be sufficient.

FocusTrapZone documentation lacks API, usage information

The FocusTrapZone control needs better documentation added to its FocusTrapZone.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Add just support

Currently the build scripts are extremely rudimentary. We should do the following:

• Hook up just to manage scripts
• Get jest running successfully, yarn test gives an error now
• Make the build option include jest
• Produce distribution bundles

Required props on a Slot can't be omitted from render

interface IFooSlotProps {
   root: { someRequiredString: string; someOptionalString?: string };
}

export const MyFooComponent = compose<IFooProps, IFooSlotProps>({
    ...restOfComposeOptions,
    render: (Slots: ISlots<IFooSlotProps>, data: IFooRenderData, ...children: React.Component[]) : JSX.Element => { 
        return <Slots.root />
    }
})

In the example above the JSX for <Slots.root /> fails to compile because it's missing someRequiredString, even though it should have been baked into the slot props as part of usePrepareProps.

Jason suggested fixing this might be as simple as adding a Partial<> around TProps in _createSlotRenderFunction

Text documentation lacks API, usage information

The Text control needs better documentation added to its Text.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Add incremental build support

Currently all builds are full builds...which is fine right now as they only take about 20 seconds total. As the repo grows this will be problematic.

Configure api-extractor

We have just tasks for api-extraction, but it is not currently configured.

Add a theme name to theme object itself so theme definitions know the name of the platform theme

Right now we send an event when the platform theme changes and custom theme definitions can be functional rather than a static JSON object, but the functional theme definition only takes a parent theme and the theme object has no obvious place for the Office theme setting.

A simple solution is simply providing a "name" to the theme object which the platform theme can fill in. This work isn't hard, it's more of a "how exactly do we want this API to look" type question than anything.

Add Box to ThemeProvider

The Fabric Web folks have a Box in their ThemeProvider to apply the background color to the region covered by the ThemeProvider. It seems like we might want to do this as well with a View. See ThemeProvider and Box here:

https://github.com/microsoft/fluent-ui-react-staging/tree/master/packages/react-theming/src/components

Build 2020 Feedback Thread - Fluent UI React Native

Welcome Build 2020 participants! Did you get a chance to try out the Fluent UI React Native library
or watch our Build 2020 talk? If so, we want to hear your feedback! The library is still in its early stages, but we wanted to show developers the direction we're taking things, and get early feedback on how we can make this even more useful to you moving forward.

Feel free to leave feedback on any of the following (and please keep feedback constructive and respectful):

• Likes
• Dislikes
• Bugs
• Areas for improvement

Thank you,
The Fluent UI React Native team

This repo should be public.

We're publishing to a public npm feed, anyway, so how private is it?

Have we crossed whatever threshold we needed that justifies making it public?

Repo should be called `fluent-ui-react-native`

This repo should be called fluent-ui-react-native for consistency with the fluent-ui-react sister repo (not fluentui-react-native).

Add publishing + beachball support

Currently none of the packages are being published or really tracked for versions. We need to add publishing support and change management support, likely using beachball.

Add better build workflow for expo playground

There's a couple different issues that can be improved with the expo playground in apps/playground.

• Even though App.tsx / package.json has no dependency on @uifabricshared packages, if you don't build the other packages in the repo the metro.config.js crashes.
• If you do add a dependency on one of the other packages, you'll need to either manually npm run build on those packages or add a tsc watch
• yarn start/Expo start is plenty fine, (or yarn build from the root) but maybe a build script should be added to package.json as well.

We should use WeakMaps for the theme settings cache instead of Symbol

Symbols seem copy-able in the babel transpilation down to ES5. Currently I'm deleting the old theme settings cache in resolvePartialTheme

@JasonVMo FYI.

Is there plans to support drop downs?

Is there plans to support drop downs soon?

Write docs for foundation-compose

Add README.md file in the directory.

Write docs for foundation-composable

Add a README.md for this package

Stack documentation lacks API, usage information

The Stack component needs better documentation added to its Stack.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Button documentation lacks API, usage information

The Button control needs better documentation added to its Button.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Hook up documentation generation

An attempt at this was done in the documentation folder using docz but it seems highly unstable and doesn't actually work. We should find some solution, likely involving gatsby, to do auto documentation.

Ideally this also includes support for mdx files.

Stand up a CI loop

This should have:

• build loop
• test loop
• ideally some of the fabric goodness like the package size monitor

Add scripts for creating packages

The repo should have scripts for creating new component packages with the correct structure.

Explore efficient *jsx helper syntax

Look at ways of removing the need to use renderSlot, instead moving to a *jsx helper syntax without creating the closures that withSlots creates.

In FluentUI-Tester App Options Web Debugger and Live Reload don't function

Repro:

1. cd apps\win32
2. yarn bundle
3. yarn run-win32
   (FluentUI Tester App Appears)
4. Click small rectangular button in top right
   (Debug menu appears)
5. Check Use Web Debugger CheckBox
   (App crashes)

Note:
Use Live Reload also doesn't work, but there is no crash

Move repo from tslint to eslint for TypeScript

This is the new industry standard and also lets us use a number of additional community plugins that only target JS

Omitting a slot from the StyleFactories drops settings from from the final slotprops

Adopting the new versions of @uifabricshared libraries forced me to introduce this work around to some components:

compose(
  ...otherstuff,
  settings,
  slots: {
    root: ReactNative.View,
    content: ReactNative.Text
  },
  styles: {
    root: [],        // Empty array 
    content: [foregroundColorTokens, textTokens]
  }
);

Without the empty array of style operations, the root slot settings get dropped from the final slot props.

All Exported Controls Should Export Examples

All exported controls from packages like experimental-web-controls should also export example usages of the controls. This makes it easier to map those directly into demo apps and more fully document them.

A potential folder structure may look something like

-- Controls-Package
---- Example-Control
------ index.ts
------ examples
------- base
------ styles
------ types
------ example-control.tsx
------ tests

fluentui-react-native/stack doesn't exist on NPM

Hello, I'm trying to use some snippets from the tester code but I can't seem to find where the fluentui-react-native/stack exists

Explore ability to add objects directly to customize

Look at the customize syntax to see if settings objects can be specified directly without expanding the types too much.

CI Loop Cleanup

The CI Loop should trigger builds on pull requests into master. There is additional work here to run code formatting and linting to make sure our repo stays clean.

Upgrade Beachball to 1.15.1

Failures in beachball may not fail the CI jobs. Upgrading to 1.15.1 will fix this.

Incorrect instructions for Fluent-Tester

https://github.com/microsoft/fluentui-react-native/tree/master/apps/fluent-tester

Current instructions:
Then go into apps\fluent-tester folder:
cd apps\fluent-tester
Build the FluentUI Tester bundle:
yarn bundle
Launch the FluentUI Tester app:
yarn run-win32

But they should be cd apps\fluent-tester\win32

Add useAsPressable implementation for Android/iOS

Right now this is a stub but there should be an implementation for these platforms. This will be necessary for getting our button code to run correctly on those platforms.

Separator documentation lacks API, usage information

The Separator control needs better documentation added to its Separator.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Turn on Eslint Rules Incrementally

Now that #16 is closed, this issue will track incremental updates to the set of tslint rules we follow.

Root slot typings are dropped when IExtractSlotProps<T> is used

Basically this:

type foo = IExtractSlotProps<{ slotProps: { root: ViewProps } }>;

// foo.root is object not ViewProps

Configure Prettier

Some level of code formatting, beyond what linters provide, is a good start

Windows Button incorrectly styled

According to Fluent design website, the Windows Button should look like this:

But currently, it looks like this:

Creating this issue to track this inconsistency. Please let me know if you have any questions.

Immutable Merge Stress Test and Cleanup

immutable-merge is incredibly core to most of the work that goes on in this repository, making sure it is performant and that the code is as tight as possible is a worthy work item

Pressable documentation lacks API, usage information

The Pressable component needs better documentation added to its Pressable.mdx documentation file. It doesn't need to be very complicated, but it does need API, prop, and usage documentation.

Use --hoist for external dependencies used across packages

Fix immutable-merge for arrays

There is a likely bug in immutable merge with array handling. Initially the checks for typeof entry === 'object' were calls to an _isPlainObject function which would omit arrays. It isn't this simple though because styles can be arrays or plain objects.

The routine ultimately needs to exclude arrays (allow the last value to win) except in the case where there is a handler function defined.

This should be validated by new test cases in the unit tests...once jest is running correctly.