Uui Documentation

UUI Documentation

UUI documentation is published on uui.epam.com. Sources are in ./app folder.

Dependency: Property Explorer configs and doc examples use @epam/uui-docs, which provides DocBuilder, TDocContext, TSkin, DocPreviewBuilder, demo API, and PE editors. The package lives in uui-docs/.

Add Doc Example

1. Go to app/src/docs/_examples and open/add folder for your component
2. Add example file: example-name.example.tsx
3. Add link in page config (app/src/docs/pages/components/<component>.json):

   {
       "id": "alert",
       "name": "Alert",
       "parentId": "components",
       "examples": [
           { "descriptionPath": "alert-descriptions" },
           { "name": "Basic", "componentPath": "alert/Basic.example.tsx" }
       ]
   }
   

4. If adding new page, register it in app/src/documents/structure/components.ts for sidebar menu
5. Open local environment (http://localhost:9009/), navigate to page, add description via RTE field

Property Explorer

Property Explorer lets users interactively test components in different prop variations. Most content is auto-generated from component prop types.

Preview vs screenshot tests: The preview function in explorerConfigs defines Preview pages for documentation — users can switch props and see changes. Screenshot tests (in e2e-testing) use these same previews to capture baseline images. Create previews here for docs; add screenshot test entries in preview.e2e.ts to include them in E2E.

Add/Update ExplorerConfig

1. Go to app/src/docs/explorerConfigs and find/add config file
2. Use same id as page config where PE should be connected
3. Add contexts:

   contexts: [
       TDocContext.Default,
       TDocContext.Resizable,
       TDocContext.Form,
       TDocContext.Table
   ]
   

4. Define bySkin mapping:

   bySkin: {
       [TSkin.UUI]: { type: '@epam/uui:TextInputProps', component: uui.TextInput },
       [TSkin.Loveship]: { type: '@epam/uui:TextInputProps', component: loveship.TextInput },
       [TSkin.Promo]: { type: '@epam/uui:TextInputProps', component: promo.TextInput },
       [TSkin.Electric]: { type: '@epam/uui:TextInputProps', component: electric.TextInput },
   }
   

5. (Optional) Override prop editor defaults:

   doc: (doc: DocBuilder<uui.TextInputProps>) => {
       doc.merge('type', { defaultValue: 'text' });
       doc.merge('maxLength', { examples: [10, 20, 30] });
   }
   

API Block

Component API section is auto-generated from prop interfaces.

Generate locally:

yarn generate-components-api

Important: You must run this command whenever public props are added, removed, or modified on any component interface (in uui-core, uui-components, or uui). Without this step, new or changed props will not appear in the Property Explorer or API docs.

External Themes

To connect external themes (not in UUI repo):

1. Add to localStorage:

   localStorage.setItem('uui-custom-themes', JSON.stringify({
       customThemes: [
           "https://cdn.example.com/theme-1",
           "https://cdn.example.com/theme-2"
       ]
   }))
   

2. Theme URL must serve /theme-manifest.json with structure:

   interface IThemeManifest {
       id: string;
       name: string;
       css: string[];
       settings?: string | null;
       propsOverride?: { [typeRef: string]: { [propName: string]: IThemeManifestPropOverride } };
   }
   

Workflow

When adding new functionality:

1. Add doc example in app/src/docs/_examples
2. Update page config to link example
3. Create/update explorerConfig for Property Explorer
4. Generate API: yarn generate-components-api
5. Test locally at http://localhost:9009/