@fluentui-react-native/text 0.13.0 → 0.14.0

package/CHANGELOG.json

@@ -2,7 +2,22 @@
   "name": "@fluentui-react-native/text",
   "entries": [
     {
-      "date": "Fri, 29 Jul 2022 21:02:36 GMT",
+      "date": "Fri, 05 Aug 2022 23:21:34 GMT",
+      "tag": "@fluentui-react-native/text_v0.14.0",
+      "version": "0.14.0",
+      "comments": {
+        "minor": [
+          {
+            "author": "email not defined",
+            "package": "@fluentui-react-native/text",
+            "commit": "4716cf81c971eed5f609a861c128dcfc4b2f0b46",
+            "comment": "Update out of date documentation (#1964)"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Fri, 29 Jul 2022 21:04:39 GMT",
       "tag": "@fluentui-react-native/text_v0.13.0",
       "version": "0.13.0",
       "comments": {

package/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Change Log - @fluentui-react-native/text
 
-This log was last generated on Fri, 29 Jul 2022 21:02:36 GMT and should not be manually modified.
+This log was last generated on Fri, 05 Aug 2022 23:21:34 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 0.14.0
+
+Fri, 05 Aug 2022 23:21:34 GMT
+
+### Minor changes
+
+- Update out of date documentation (#1964) (email not defined)
+
 ## 0.13.0
 
-Fri, 29 Jul 2022 21:02:36 GMT
+Fri, 29 Jul 2022 21:04:39 GMT
 
 ### Minor changes
 

package/MIGRATION.md

@@ -0,0 +1,98 @@
+# Text Migration
+
+## Migration from v0 Text
+
+In the short term, the new `Text` control is named `TextV1` while it clashes with the existing older control. Once we deprecate the old control, it will be renamed to `Text`. It may be useful to rename the control to `Text` using the import syntax to simplify the rename:
+
+```ts
+import { TextV1 as Text } from '@fluentui-react-native/text';
+```
+
+### Component renames
+
+| v0 `Text`                   | v1 `Text`                   |
+| --------------------------- | --------------------------- |
+| `<Text>Hello, World</Text>` | `<Text>Hello, World</Text>` |
+
+### Props unchanged
+
+- Any props that are part of `ViewProps` and `TextProps` from `react-native`
+- `color`
+
+### Props changed
+
+- `variant` => Prop name remains identical, but will support a different collection of named font variants. Newly defined v1 variants can be found in [Typography.types](../../theming/theme-types/src/Typography.types.ts) under theme-types.
+
+### Props added
+
+- `align`
+- `block`
+- `font`
+- `italic`
+- `strikethrough`
+- `size`
+- `truncate`
+- `underline`
+- `weight`
+- `wrap`
+
+### Props removed
+
+- `disabled` is not supported in the v1 Text
+
+### Tokens unchanged
+
+- Any props that are part of `FontTokens`, `IForegroundColorTokens`
+
+### Tokens changed
+
+- Global font tokens have been editted according to design token redlines
+
+| Token       | Win32         |
+| ----------- | ------------- |
+| Family      |               |
+| `Base`      | `SegoeUI`     |
+| `Monospace` | `Consolas`    |
+| `Numeric`   | `Bahnschrift` |
+| Size        |               |
+| `100`       | `10px`/`14px` |
+| `200`       | `12px`/`16px` |
+| `300`       | `14px`/`20px` |
+| `400`       | `16px`/`22px` |
+| `500`       | `20px`/`26px` |
+| `600`       | `24px`/`32px` |
+| `700`       | `28px`/`36px` |
+| `800`       | `32px`/`40px` |
+| `900`       | `40px`/`52px` |
+| `1000`      | `68px`/`92px` |
+| Weight      |               |
+| `Regular`   | `400`         |
+| `Medium`    | `500`         |
+| `Semibold`  | `600`         |
+| `Bold`      | `700`         |
+
+### Tokens not supported natively on win32
+
+- `lineHeight`
+- `letterSpacing`
+- `textDecorationColor`
+- `textShadowColor`
+- `textShadowOffset`
+- `textShadowRadius`
+- `textTransform`
+
+### Updating ThemeProvider
+
+If you are using the older theme provider `ThemeProvider` from `@uifabricshared/theming-react-native`, you will need to update the `ThemeProvider` to pull from `@fluentui-react-native/theme` to have the control work properly with themes. Please see [this page](../../../docs/pages/Guides/UpdateThemeProvider.md) for guidance.
+
+### Migrating customized Text
+
+Please see [this page](../../../docs/pages/Guides/UpdatingCustomize.md) for guidance on how to move from the old `customize` API to the new one.
+
+### Other Prop differences
+
+- `block` => On win32, instead of setting it as a boolean prop, block display is applied by default, and is overridden as inline when `<Text>` is wrapped by a parent `<Text>`.
+
+### Slot differences
+
+There are no slot differences for FURN `Text`

package/README.md

@@ -0,0 +1,5 @@
+# Text
+
+A cross-platform Text component using the Fluent Design System.
+
+Text V1 supported platforms: win32

package/SPEC.md

@@ -0,0 +1,235 @@
+# Text
+
+In the short term, the new `Text` control is named `TextV1` while it clashes with the existing older control. Once we deprecate the old control, it will be renamed to `Text`. It may be useful to rename the control to `Text` using the import syntax to simplify the rename:
+
+```ts
+import { TextV1 as Text } from '@fluentui-react-native/text';
+```
+
+FURN components that have imported from experimental-text now use the above syntax to use `TextV1`.
+
+## Background
+
+The `Text` component is for displaying text, and supports nesting, styling, and touch handling.
+
+## Requirements
+
+If using FURN's theming, the `Text` requires use of the `ThemeProvider` from `@fluentui-react-native/theme` to work properly with themes. Please see [this page](../../../docs/pages/Guides/UpdateThemeProvider.md) for information on updating your `ThemeProvider` if using the version from `@uifabricshared/theming-react-native`.
+
+## Sample Code
+
+Basic example:
+
+```jsx
+<Text>Hello World</Text>
+```
+More examples on the [Test pages for Text](../../../apps/fluent-tester/src/TestComponents/TextExperimental). Instructions on running the tester app can be found [here](../../../apps/fluent-tester/README.md).
+
+## Visual Examples
+
+Win32:
+
+![Underlined Text on win32 example](./assets/Text_example_underlined_win32.png)
+
+```jsx
+<Text underline>This line has been underlined and striked through</Text>
+```
+
+![Block Text on win32 example](./assets/Text_example_block_win32.png)
+
+```jsx
+<>
+  <Text>Every block of text gets its own line.</Text>
+  <Text>This is a new block</Text>
+</>
+```
+
+![Inline Text on win32 example](./assets/Text_example_inline_win32.png)
+
+```jsx
+<Text>
+  <Text>Text components inside a parent text component is inline text</Text>
+  <Text>This entire block is a RichLabel.</Text>
+</Text>
+```
+
+![Customized Text on win32 example](./assets/Text_example_customized_win32.png)
+
+```jsx
+const RedCaptionBold = Text.customize({ variant: 'captionStandard', fontWeight: '700', color: '#ff0000' });
+<RedCaptionBold>RedCaptionBold</RedCaptionBold>
+```
+
+![Text Variants on win32 example](./assets/Text_example_variants_win32.png)
+V1 `Text` component supports variant types that have preset font family, size, and weight values.
+
+```jsx
+<Caption1>Caption1</Caption1>
+<Body1>Body1</Body1>
+<Body1Strong>Body1Strong</Body1Strong>
+<Body2>Body2</Body2>
+<Body2Strong>Body2Strong</Body2Strong>
+<Subtitle2>Subtitle2</Subtitle2>
+<Subtitle2Strong>Subtitle2Strong</Subtitle2Strong>
+<Subtitle1>Subtitle1</Subtitle1>
+<Subtitle1Strong>Subtitle1Strong</Subtitle1Strong>
+<Title1>Title1</Title1>
+<Title1Strong>Title1Strong</Title1Strong>
+<LargeTitle>LargeTitle</LargeTitle>
+<Display>Display</Display>
+```
+
+![Pressable Text on win32 example](./assets/Text_example_pressable_win32.png)
+
+```jsx
+<Text variant={'bodyStandard'}>
+  Press{' '}
+  <Text
+  variant={'bodyStandard'}
+  color="blue"
+  keyDownEvents={handledNativeKeyboardEvents}
+  onPress={_onPress2}
+  onKeyDown={_onKeyDown2}
+  >
+  here
+  </Text>{' '}
+  to view an alert.
+  </Text>
+```
+
+## API
+
+The `Text` control is rendered as a `react-native` Text(`RNText`). However, `RNText`and `Text` do not align in their set of props entirely.
+
+### Props
+
+Below is the set of props the Text supports:
+
+```ts
+export type TextProps<TBase = ITextProps> = TBase &
+  FontVariantTokens & {
+    /**
+     * foreground text color
+     */
+    color?: ColorValue;
+
+    /**
+     * Aligns text based on the parent container.
+     *
+     * @defaultValue start
+     */
+    align?: TextAlign;
+
+    /**
+     * Applies a block display for the content.
+     *
+     * @defaultValue false
+     */
+    block?: boolean;
+
+    /**
+     * Applies the font family to the content.
+     *
+     * @defaultValue base
+     */
+    font?: TextFont;
+
+    /**
+     * Applies the italic font style to the content.
+     *
+     * @defaultValue false
+     */
+    italic?: boolean;
+
+    /**
+     * Applies the strikethrough text decoration to the content.
+     *
+     * @defaultValue false
+     */
+    strikethrough?: boolean;
+
+    /**
+     * Applies font size and line height based on the theme tokens.
+     *
+     * @defaultValue 300
+     */
+    size?: TextSize;
+
+    /**
+     * Truncate overflowing text for block displays.
+     *
+     * @defaultValue false
+     */
+    truncate?: boolean;
+
+    /**
+     * Applies the underline text decoration to the content.
+     *
+     * @defaultValue false
+     */
+    underline?: boolean;
+
+    /**
+     * Applies font weight to the content.
+     *
+     * @defaultValue regular
+     */
+    weight?: TextWeight;
+
+    /**
+     * Wraps the text content on white spaces.
+     *
+     * @defaultValue true
+     */
+    wrap?: boolean;
+  };
+
+8/1/22 Notes:
+
+- `block` => On win32, instead of setting it as a boolean prop, block display is applied by default, and is overridden as inline when `<Text>` is wrapped by a parent `<Text>`.
+
+- `font` => According to design token redlines, `font` prop is given a giant string with a delimiter of font families for each enum type (`base`/`numeric`/`monospace`), We currently don't have a way to deal with this fontFamily format. We only support a single font family for each font type.
+```
+
+### Styling Tokens
+
+Tokens can be used to customize the styling of the control by using the `customize` function on the `Text`. For more information on using the `customize` API, please see [this page](../../framework/composition/README.md). The `Text` has the following tokens:
+
+```ts
+export type TextTokens = FontTokens & IForegroundColorTokens & TextStyle;
+```
+
+## Behaviors
+
+### Pressable Text
+
+`Text` can be rendered as pressable.
+
+### Interaction
+
+#### Keyboard interaction
+
+The following is a set of keys that interact with the `Text` component:
+
+| Key     | Description                                                     |
+| ------- | --------------------------------------------------------------- |
+| `Tab`   | If `onPress` or `focusable` is set, component will gain focus.  |
+| `Space` | Executes the function passed into the `onPress` prop.           |
+
+#### Cursor interaction for Pressable Text
+
+- Cursor moves onto pressable text: Should immediately change the styling of the `Text` so that it appears to be hovered.
+- Cursor moves out of pressable text: Should immediately remove the hovered styling of the `Text`.
+- Mouse click: Should handle `onPress` event of `Text` and move focus to its target.
+
+#### Touch interaction
+
+The same behavior as above translated for touch events. This means that there is no equivalent for `onHoverIn` and `onHoverOut`, which makes it so that the hovered state cannot be accessed.
+
+## Accessibility
+
+### Expected behavior
+
+- Should mix in the accessibility props expected for a `Text` component.
+- Should be keyboard tabbable and focusable.
+- onAccessibilityTap defaults to onPress unless set otherwise

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentui-react-native/text",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A cross-platform Text component using the Fluent Design System",
   "main": "lib-commonjs/index.js",
   "module": "lib/index.js",