feat(docs): add developer-friendly documentation for each example

akveo · Mar 11, 2020 · 38d073e · 38d073e
1 parent 12c2654
commit 38d073e
Show file tree

Hide file tree

Showing 105 changed files with 1,517 additions and 726 deletions.
diff --git a/docs/src/app/@theme/services/highlight.service.ts b/docs/src/app/@theme/services/highlight.service.ts
@@ -5,6 +5,6 @@ import * as hljs from 'highlight.js';
 export class NgdHighlightService {
 
   public highlight(code: string): string {
-    return hljs.highlightAuto(code, ['ts', 'html', 'scss', 'nginx']).value;
+    return hljs.highlightAuto(code, ['js', 'jsx', 'ts', 'tsx', 'json']).value;
   }
 }
diff --git a/docs/src/app/blocks/components/code-block/code-block.component.scss b/docs/src/app/blocks/components/code-block/code-block.component.scss
@@ -9,7 +9,7 @@
     display: flex;
     padding: 0;
     font-size: 1rem;
-    border-radius: 0.5rem;
+    border-radius: 0.25rem;
     background: $code-block-bg;
     overflow-x: auto;
 

diff --git a/docs/src/app/blocks/components/live-example-block/live-example-block.component.scss b/docs/src/app/blocks/components/live-example-block/live-example-block.component.scss
@@ -6,7 +6,7 @@
   // colors
   $action-bg: white;
   $action-fg: nb-theme(color-fg-heading-light);
-  $block-bg-default: #edf0f4;
+  $block-bg-default: nb-theme(background-basic-color-3);
   $block-bg-cosmic: #1b1b38;
   $block-fg-cosmic: #e8e9fa;
   $block-bg-corporate: #edf0f4;
@@ -16,15 +16,15 @@
   display: flex;
   flex-direction: column;
   padding: 0.5rem 1rem 2.5rem 1.5rem;
-  border-radius: 0.5rem;
+  border-radius: 0.25rem;
   position: relative;
 
   .header {
     display: flex;
     flex-wrap: wrap;
     align-items: center;
     justify-content: space-between;
-    margin-bottom: 1.875rem;
+    margin-bottom: 1rem;
   }
 
   .title-caption {
@@ -62,7 +62,7 @@
 
   .action-item {
     background-color: $action-bg;
-    border-radius: 0.375rem;
+    border-radius: 0.25rem;
     height: 100%;
     line-height: 1;
     border: none;

diff --git a/docs/src/app/blocks/components/overview-example-block/overview-example-block.component.ts b/docs/src/app/blocks/components/overview-example-block/overview-example-block.component.ts
@@ -13,7 +13,9 @@ import {
 @Component({
   selector: 'ngd-overview-example',
   template: `
-    <h5 style="margin-top: 2rem">{{title}}:</h5>
+    <td>
+      <div *ngIf="title" ngdDescription>{{title}}</div>
+    </td>
     <ngd-code-block [code]="code"></ngd-code-block>
   `,
   changeDetection: ChangeDetectionStrategy.OnPush,
@@ -25,7 +27,8 @@ export class NgdOverviewExampleBlock {
 
   @Input('example')
   set example(value) {
-    this.code = value.code.replace(/```/g, '');
-    this.title = value.description;
+    this.code = value.code.replace(/```/g, '')
+                     .replace(/^\s+|\s+$/g, '');
+    this.title = value.shortDescription;
   }
 }
diff --git a/docs/src/app/documentation/page/page.component.scss b/docs/src/app/documentation/page/page.component.scss
@@ -11,7 +11,8 @@
   $settings-margin: nb-theme(settings-col-margin);
   $heading-light: nb-theme(color-fg-heading-light);
   $code-bg: #f1f2f3;
-  $code-fg: nb-theme(color-info-500);
+  $code-bg: nb-theme(background-basic-color-3);
+  $code-fg: nb-theme(color-primary-500);
   $code-block-bg: nb-theme(code-block-bg);
   $table-head-fg: #8994a3;
   $table-border: 1px solid #f1f2f3;

diff --git a/docs/src/structure.ts b/docs/src/structure.ts
@@ -248,14 +248,6 @@ export const structure = [
         type: 'group',
         name: 'Styling & Theming',
       },
-      {
-        type: 'tabs',
-        name: 'Application Provider',
-        icon: 'application-provider.svg',
-        source: [
-          'ApplicationProvider',
-        ],
-      },
       {
         type: 'tabs',
         name: 'Using Mapping',
@@ -278,6 +270,22 @@ export const structure = [
         type: 'group',
         name: 'Global',
       },
+      {
+        type: 'tabs',
+        name: 'Application Provider',
+        icon: 'application-provider.svg',
+        source: [
+          'ApplicationProvider',
+        ],
+      },
+      {
+        type: 'tabs',
+        name: 'Layout',
+        icon: 'layout.svg',
+        source: [
+          'Layout',
+        ],
+      },
       {
         type: 'tabs',
         name: 'Text',
@@ -294,10 +302,16 @@ export const structure = [
       },
       {
         type: 'tabs',
-        name: 'Layout',
-        icon: 'layout.svg',
+        name: 'Icon',
+        icon: 'icon.svg',
         source: [
-          'Layout',
+          'Icon',
+        ],
+        overview: [
+          {
+            name: 'Icon',
+            images: ['icon.png'],
+          },
         ],
       },
       {
@@ -323,20 +337,6 @@ export const structure = [
           },
         ],
       },
-      {
-        type: 'tabs',
-        name: 'Icon',
-        icon: 'icon.svg',
-        source: [
-          'Icon',
-        ],
-        overview: [
-          {
-            name: 'Icon',
-            images: ['icon.png'],
-          },
-        ],
-      },
       {
         type: 'group',
         name: 'Navigation',
@@ -387,6 +387,16 @@ export const structure = [
           },
         ],
       },
+      {
+        type: 'tabs',
+        name: 'Menu',
+        icon: 'menu.svg',
+        source: [
+          'Menu',
+          'MenuGroup',
+          'MenuItem',
+        ],
+      },
       {
         type: 'tabs',
         name: 'Drawer',
@@ -403,16 +413,6 @@ export const structure = [
           },
         ],
       },
-      {
-        type: 'tabs',
-        name: 'Menu',
-        icon: 'menu.svg',
-        source: [
-          'Menu',
-          'MenuGroup',
-          'MenuItem',
-        ],
-      },
       {
         type: 'tabs',
         name: 'View Pager',
@@ -425,20 +425,6 @@ export const structure = [
         type: 'group',
         name: 'Forms',
       },
-      {
-        type: 'tabs',
-        name: 'Input',
-        icon: 'input.svg',
-        source: [
-          'Input',
-        ],
-        overview: [
-          {
-            name: 'Input',
-            images: ['input.png'],
-          },
-        ],
-      },
       {
         type: 'tabs',
         name: 'Button',
@@ -462,6 +448,21 @@ export const structure = [
           },
         ],
       },
+      {
+        type: 'tabs',
+        name: 'Radio',
+        icon: 'radio.svg',
+        source: [
+          'RadioGroup',
+          'Radio',
+        ],
+        overview: [
+          {
+            name: 'Radio',
+            images: ['radio.png'],
+          },
+        ],
+      },
       {
         type: 'tabs',
         name: 'Toggle',
@@ -478,16 +479,15 @@ export const structure = [
       },
       {
         type: 'tabs',
-        name: 'Radio',
-        icon: 'radio.svg',
+        name: 'Input',
+        icon: 'input.svg',
         source: [
-          'RadioGroup',
-          'Radio',
+          'Input',
         ],
         overview: [
           {
-            name: 'Radio',
-            images: ['radio.png'],
+            name: 'Input',
+            images: ['input.png'],
           },
         ],
       },
@@ -504,29 +504,29 @@ export const structure = [
       },
       {
         type: 'tabs',
-        name: 'Datepicker',
-        icon: 'datepicker.svg',
+        name: 'Autocomplete',
+        icon: 'autocomplete.svg',
         source: [
-          'Datepicker',
-          'RangeDatepicker',
+          'Autocomplete',
         ],
         overview: [
           {
-            name: 'Datepicker',
+            name: 'Autocomplete',
             images: [],
           },
         ],
       },
       {
         type: 'tabs',
-        name: 'Autocomplete',
-        icon: 'autocomplete.svg',
+        name: 'Datepicker',
+        icon: 'datepicker.svg',
         source: [
-          'Autocomplete',
+          'Datepicker',
+          'RangeDatepicker',
         ],
         overview: [
           {
-            name: 'Autocomplete',
+            name: 'Datepicker',
             images: [],
           },
         ],

diff --git a/src/components/theme/application/applicationProvider.component.tsx b/src/components/theme/application/applicationProvider.component.tsx
@@ -36,7 +36,6 @@ interface State {
 
 /**
  * Overall application container.
- * Provides Eva styles to UI Kitten components.
  *
  * @extends React.Component
  *
@@ -58,20 +57,43 @@ interface State {
  * Usually, can be provided by `@ui-kitten/metro-config` package.
  *
  * @overview-example Simple Usage
- *
+ * ApplicationProvider is designed to be the root component of the application.
+ * It should be rendered **once**, to provide Eva styles for nested components.
  * ```
  * import React from 'react';
  * import { ApplicationProvider, Layout, Text } from '@ui-kitten/components';
  * import * as eva from '@eva-design/eva';
  *
  * export default () => (
- *   <ApplicationProvider {...eva} theme={eva.light}>
- *     <Layout style={{ flex: 1 }}>
+ *   <ApplicationProvider {...eva} theme={eva.light}> // <-- {eva.dark} for dark mode
+ *     <Layout style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
  *       <Text>Welcome to UI Kitten</Text>
  *     </Layout>
  *   </ApplicationProvider>
  * );
  * ```
+ *
+ * @overview-example Ecosystem
+ * Also, it may accept [custom themes](https://akveo.github.io/react-native-ui-kitten/docs/guides/branding)
+ * and [icon packages](https://akveo.github.io/react-native-ui-kitten/docs/guides/icon-packages)
+ * to provide a highly customizable, design system based application.
+ * ```
+ * import React from 'react';
+ * import { ApplicationProvider, IconRegistry, Layout, Text } from '@ui-kitten/components';
+ * import { EvaIconsPack } from '@ui-kitten/eva-icons';
+ * import * as eva from '@eva-design/eva';
+ *
+ * export default () => (
+ *   <React.Fragment>
+ *     <IconRegistry icons={EvaIconsPack} />
+ *     <ApplicationProvider {...eva} theme={{ ...eva.light, ...myTheme }}>
+ *       <Layout style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+ *         <Text>Welcome to UI Kitten</Text>
+ *       </Layout>
+ *     </ApplicationProvider>
+ *   </React.Fragment>
+ * );
+ * ```
  */
 export class ApplicationProvider extends React.Component<ApplicationProviderProps, State> {
 

diff --git a/src/components/ui/autocomplete/autocomplete.component.tsx b/src/components/ui/autocomplete/autocomplete.component.tsx
@@ -98,12 +98,19 @@ interface State {
  * @property {InputProps} ...InputProps - Any props applied to Input component.
  *
  * @overview-example AutocompleteSimpleUsage
+ * Autocomplete may contain options to be rendered within suggestions list.
+ * Options should be provided by passing them to children.
  *
  * @overview-example AutocompleteAccessories
+ * Autocomplete may contain accessories by passing `accessoryLeft` or `accessoryRight` props.
+ * By default, we expect it to be images.
  *
  * @example AutocompleteHandleKeyboard
+ * On mobile devices, options may be overlapped by keyboard.
+ * It can be handled with `placement` property.
  *
  * @example AutocompleteAsync
+ * For requesting a real-world data by typing, http requests may be sent with debounce.
  */
 export class Autocomplete extends React.Component<AutocompleteProps, State> {
 

diff --git a/src/components/ui/avatar/avatar.component.tsx b/src/components/ui/avatar/avatar.component.tsx
@@ -48,8 +48,10 @@ export type AvatarElement = React.ReactElement<AvatarProps>;
  * @overview-example AvatarSimpleUsage
  *
  * @overview-example AvatarSize
+ * Avatar can be resized by passing `size` property.
  *
  * @overview-example AvatarShape
+ * Also, it may have different shape configurable with `shape` property.
  */
 export class AvatarComponent extends React.Component<AvatarProps> {