@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-admin-ui/nav-menu/index.md

@@ -0,0 +1,97 @@
+---
+title: 'Modify the Nav Menu'
+weight: 5
+---
+
+The Nav Menu is the main navigation for the Admin UI, located on the left-hand side when in desktop mode. It is used to provide top-level
+access to routes in the app, and can be extended and modified by UI extensions.
+
+## Extending the NavMenu
+
+Once you have defined some custom routes, you need some way for the administrator to access them. For this you will use the [addNavMenuItem](/reference/admin-ui-api/nav-menu/add-nav-menu-item/) and [addNavMenuSection](/reference/admin-ui-api/nav-menu/add-nav-menu-section) functions.
+
+Let's add a new section to the Admin UI main nav bar containing a link to the "greeter" module from the [Getting Started guide](/guides/extending-the-admin-ui/getting-started/#routes) example:
+
+```ts title="src/plugins/greeter/ui/providers.ts"
+import { addNavMenuSection } from '@vendure/admin-ui/core';
+
+export default [
+    addNavMenuSection({
+        id: 'greeter',
+        label: 'My Extensions',
+        items: [{
+            id: 'greeter',
+            label: 'Greeter',
+            routerLink: ['/extensions/greet'],
+            // Icon can be any of https://core.clarity.design/foundation/icons/shapes/
+            icon: 'cursor-hand-open',
+        }],
+    },
+    // Add this section before the "settings" section
+    'settings'),
+];
+```
+
+Now we must also register these providers with the compiler:
+
+```ts title="src/vendure-config.ts"
+import path from 'path';
+import { VendureConfig } from '@vendure/core';
+import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        AdminUiPlugin.init({
+            port: 3002,
+            app: compileUiExtensions({
+                outputPath: path.join(__dirname, '../admin-ui'),
+                extensions: [
+                    {
+                        id: 'greeter',
+                        extensionPath: path.join(__dirname, 'plugins/greeter/ui'),
+                        routes: [{ route: 'greet', filePath: 'routes.ts' }],
+                        // highlight-start
+                        providers: ['providers.ts']
+                        // highlight-end
+                    },
+                ],
+            }),
+        }),
+    ],
+};
+```
+
+Running the server will compile our new shared module into the app, and the result should look like this:
+
+![./ui-extensions-navbar.webp](./ui-extensions-navbar.webp)
+
+## Overriding existing nav items
+
+It is also possible to override one of the default (built-in) nav menu sections or items. This can be useful for example if you wish to provide a completely different implementation of the product list view.
+
+This is done by setting the `id` property to that of an existing nav menu section or item. The `id` can be found by inspecting the link element in your browser's dev tools for the `data-item-id` attribute:
+
+![Navbar menu id](./nav-menu-id.webp)
+
+## Removing existing nav items
+
+If you would like to remove an existing nav item, you can do so by overriding it and setting the `requiresPermission` property to an invalid value:
+
+```ts title="src/plugins/greeter/ui/providers.ts"
+import { SharedModule, addNavMenuItem} from '@vendure/admin-ui/core';
+
+export default [
+    addNavMenuItem({
+        id: 'collections',  // <-- we will override the "collections" menu item
+        label: 'Collections',
+        routerLink: ['/catalog', 'collections'],
+        // highlight-start
+        // we use an invalid permission which ensures it is hidden from all users
+        requiresPermission: '__disable__'
+        // highlight-end
+    },
+    'catalog'),
+];
+```

package/docs/guides/extending-the-admin-ui/page-tabs/index.md

@@ -0,0 +1,44 @@
+---
+title: 'Page Tabs'
+weight: 5
+---
+
+You can add your own tabs to any of the Admin UI's list or detail pages using the [registerPageTab](/reference/admin-ui-api/tabs/register-page-tab/) function. For example, to add a new tab to the product detail page for displaying product reviews:
+
+```ts title="src/plugins/reviews/ui/providers.ts"
+import { registerPageTab } from '@vendure/admin-ui/core';
+
+import { ReviewListComponent } from './components/review-list/review-list.component';
+
+export default [
+    registerPageTab({
+        location: 'product-detail',
+        tab: 'Reviews',
+        route: 'reviews',
+        tabIcon: 'star',
+        component: ReviewListComponent,
+    }),
+];
+```
+
+![./ui-extensions-tabs.webp](./ui-extensions-tabs.webp)
+
+If you want to add page tabs to a custom admin page, specify the `locationId` property:
+
+```ts title="src/plugins/my-plugin/ui/routes.ts"
+import { registerRouteComponent } from '@vendure/admin-ui/core';
+import { TestComponent } from './components/test/test.component';
+
+export default [
+    registerRouteComponent({
+        component: TestComponent,
+        title: 'Test',
+        // highlight-next-line
+        locationId: 'my-location-id'
+    }),
+];
+```
+
+:::note
+Currently it is only possible to define new tabs using Angular components.
+:::

package/docs/guides/extending-the-admin-ui/ui-library/index.md

@@ -0,0 +1,356 @@
+---
+title: "UI Component Library"
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The Admin UI is built on a customized version of the [Clarity Design System](https://clarity.design/documentation/get-started). This means that if you are writing Angular-based UI extensions, you can use the same components that are used in the rest of the Admin UI. If you are using React, we are gradually exporting the most-used components for use with React.
+
+## Buttons
+
+![Buttons](./buttons.webp)
+
+There are three types of button:
+
+- **Regular**: These are general-purpose buttons available in a number of styles. They are used in the action bar and as confirmation buttons for dialogs.
+- **Ghost**: This style is primarily used to indicate a column in a table which is a link to a detail view.
+- **Small**: This style is used for secondary actions of less prominence than a standard button, or when the button must fit in a small space.
+
+
+<Tabs groupId="framework">
+<TabItem value="Angular" label="Angular" default>
+
+
+```html
+<button class="button primary">Primary</button>
+<button class="button secondary">Secondary</button>
+<button class="button success">Success</button>
+<button class="button warning">Warning</button>
+<button class="button danger">Danger</button>
+
+<button class="button-ghost">Ghost</button>
+<a class="button-ghost" [routerLink]="['/extensions/my-plugin/my-custom-route']">
+    <clr-icon shape="arrow" dir="right"></clr-icon>
+    John Smith
+</a>
+
+<button class="button-small">Small</button>
+<button class="button-small">
+    <clr-icon shape="layers"></clr-icon>
+    Assign to channel
+</button>
+```
+
+</TabItem>
+<TabItem value="React" label="React">
+
+```tsx
+import React from 'react';
+import { CdsIcon, Link } from '@vendure/admin-ui/react';
+
+export function DemoComponent() {
+    return (
+        <>
+            <button className="button primary">Primary</button>
+            <button className="button secondary">Secondary</button>
+            <button className="button success">Success</button>
+            <button className="button warning">Warning</button>
+            <button className="button danger">Danger</button>
+            
+            <button className="button-ghost">Ghost</button>
+            <Link className="button-ghost" href="/extensions/my-plugin/my-custom-route">
+                <CdsIcon icon={arrowIcon} direction="right" />
+                John Smith
+            </Link>
+            
+            <button className="button-small">Small</button>
+            <button className="button-small">
+                <CdsIcon icon={layersIcon} />
+                Assign to channel
+            </button>
+        </>
+    );
+}
+```
+
+</TabItem>
+</Tabs>
+
+
+## Icons
+
+You can use the built-in [Clarity Icons](https://core.clarity.design/foundation/icons/shapes/) for a consistent look-and-feel with the rest of the 
+Admin UI app.
+
+![Icons](./icons.webp)
+
+
+
+<Tabs groupId="framework">
+<TabItem value="Angular" label="Angular" default>
+
+
+```html
+<clr-icon shape="star" size="8"></clr-icon>
+<clr-icon shape="star" size="16"></clr-icon>
+<clr-icon shape="star" size="24"></clr-icon>
+<clr-icon shape="star" size="36"></clr-icon>
+<clr-icon shape="star" size="48"></clr-icon>
+<clr-icon shape="star" size="56"></clr-icon>
+
+<clr-icon shape="user" class="has-badge--success"></clr-icon>
+<clr-icon shape="user" class="has-alert"></clr-icon>
+<clr-icon shape="user" class="has-badge--info"></clr-icon>
+<clr-icon shape="user" class="has-badge--error"></clr-icon>
+
+<clr-icon shape="user" class="is-success"></clr-icon>
+<clr-icon shape="user" class="is-info"></clr-icon>
+<clr-icon shape="user" class="is-warning"></clr-icon>
+<clr-icon shape="user" class="is-error"></clr-icon>
+```
+
+</TabItem>
+<TabItem value="React" label="React">
+
+```tsx
+import React from 'react';
+import { starIcon, userIcon } from '@cds/core/icon';
+import { CdsIcon } from '@vendure/admin-ui/react';
+
+export function DemoComponent() {
+    return (
+        <>
+            <CdsIcon icon={starIcon} size="xs" />
+            <CdsIcon icon={starIcon} size="sm" />
+            <CdsIcon icon={starIcon} size="md" />
+            <CdsIcon icon={starIcon} size="lg" />
+            <CdsIcon icon={starIcon} size="xl" />
+            <CdsIcon icon={starIcon} size="xxl" />
+            
+            <CdsIcon icon={userIcon} badge="success" />
+            <CdsIcon icon={userIcon} badge="info" />
+            <CdsIcon icon={userIcon} badge="warning" />
+            <CdsIcon icon={userIcon} badge="danger" />
+            
+            <CdsIcon icon={userIcon} status="success" />
+            <CdsIcon icon={userIcon} status="info" />
+            <CdsIcon icon={userIcon} status="warning" />
+            <CdsIcon icon={userIcon} status="danger" />
+        </>
+    );
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Form inputs
+
+Form inputs are styled globally, so you don't need to use special components for these. The label & tooltip styling is controlled by the
+"form field" wrapper component.
+
+![Form input](./form-inputs.webp)
+
+
+<Tabs groupId="framework">
+<TabItem value="Angular" label="Angular" default>
+
+
+```html
+<div class="form-grid">
+    <vdr-form-field label="Page title">
+        <input type="text" />
+    </vdr-form-field>
+    <vdr-form-field label="Select input">
+        <select>
+            <option>Option 1</option>
+            <option>Option 2</option>
+        </select>
+    </vdr-form-field>
+    <vdr-form-field label="Checkbox input">
+        <input type="checkbox" />
+    </vdr-form-field>
+    <vdr-form-field label="Textarea input">
+        <textarea></textarea>
+    </vdr-form-field>
+    <vdr-form-field label="With tooltip" tooltip="This is a tooltip for the form input">
+        <input type="text" />
+    </vdr-form-field>
+    <vdr-form-field label="Invalid with error">
+        <input type="text" [formControl]="invalidFormControl" />
+    </vdr-form-field>
+    <vdr-rich-text-editor
+        class="form-grid-span"
+        label="Description"
+    ></vdr-rich-text-editor>
+</div>
+```
+
+</TabItem>
+<TabItem value="React" label="React">
+
+```tsx
+import React from 'react';
+import { starIcon, userIcon } from '@cds/core/icon';
+import { FormField, RichTextEditor } from '@vendure/admin-ui/react';
+
+export function DemoComponent() {
+    return (
+        <div className="form-grid">
+            <FormField label="Page title">
+                <input type="text" />
+            </FormField>
+            <FormField label="Select input">
+                <select>
+                    <option>Option 1</option>
+                    <option>Option 2</option>
+                </select>
+            </FormField>
+            <FormField label="Checkbox input">
+                <input type="checkbox" />
+            </FormField>
+            <FormField label="Textarea input">
+                <textarea />
+            </FormField>
+            <FormField label="With tooltip" tooltip="This is a tooltip for the form input">
+                <input type="text" />
+            </FormField>
+            <FormField label="Invalid with error" invalid>
+                <input type="text" />
+            </FormField>
+            <RichTextEditor className="form-grid-span" label="Description" readOnly={false} />
+        </div>
+    );
+}
+```
+
+</TabItem>
+</Tabs>
+
+The `form-grid` class is used to lay out the form fields into a 2-column grid on larger screens, and a single column on smaller screens.
+If you want to force a particular field to always take up the full width (i.e. to span 2 columns at all screen sizes), you can add the
+`form-grid-span` class to that form field.
+
+```html
+<div class="form-grid">
+    // highlight-next-line
+    <vdr-form-field label="Page title" class="form-grid-span">
+        <input type="text" />
+    </vdr-form-field>
+</div>
+```
+
+## Cards
+
+Cards are used as a general-purpose container for page content, as a way to visually group related sets of components.
+
+![Card](./card.webp)
+
+
+<Tabs groupId="framework">
+<TabItem value="Angular" label="Angular" default>
+
+
+```html
+<vdr-card title="Card">
+    This is a card. On a detail page, content should usually be placed inside a card.
+</vdr-card>
+```
+
+</TabItem>
+<TabItem value="React" label="React">
+
+```tsx
+import React from 'react';
+import { Card } from '@vendure/admin-ui/react';
+
+export function DemoComponent() {
+    return (
+        <Card title="Card">
+            This is a card. On a detail page, content should usually be placed inside a card.
+        </Card>
+    );
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Layout
+
+The following layout components are available:
+
+- Page block: This is a wrapper which applies consistent margins and max-width to the contents of the page. In general, the contents of a page should always be wrapped in this component except when using the DataTable2 component, which has its own styling for margins and width.
+- Action bar: This is a wrapper for the top area of the page, just below the header section. This is where the primary action buttons for the page should be located.
+- Page detail layout: For detail views, this wrapper provides a two-column layout with a main content area and a sidebar.
+
+![Layout](./layout.webp)
+
+
+<Tabs groupId="framework">
+<TabItem value="Angular" label="Angular" default>
+
+
+```html
+<vdr-page-block>
+    <vdr-action-bar>
+        <vdr-ab-left>Action bar left contents</vdr-ab-left>
+        <vdr-ab-right>
+            <button class="button primary">Primary action</button>
+        </vdr-ab-right>
+    </vdr-action-bar>
+</vdr-page-block>
+<vdr-page-detail-layout>
+    <vdr-page-detail-sidebar>
+        <vdr-card>Sidebar content</vdr-card>
+    </vdr-page-detail-sidebar>
+    <vdr-page-block>
+        <vdr-card title="Card">
+            This is a card. On a detail page, content should usually be placed inside a card.
+        </vdr-card>
+    </vdr-page-block>
+</vdr-page-detail-layout>
+```
+
+</TabItem>
+<TabItem value="React" label="React">
+
+```tsx
+import React from 'react';
+import { 
+    ActionBar,
+    Card,
+    PageBlock,
+    PageDetailLayout,
+} from '@vendure/admin-ui/react';
+
+export function DemoComponent() {
+    return (
+        <>
+            <PageBlock>
+                <ActionBar leftContent={<div>Action bar left contents</div>}>
+                    <button className="button primary">Primary action</button>
+                </ActionBar>
+            </PageBlock>
+
+            <PageDetailLayout
+                sidebar={
+                    <div>
+                        <Card>Sidebar content</Card>
+                    </div>
+                }
+            >
+                <PageBlock>
+                    <Card title="Card">
+                        This is a card. On a detail page, content should usually be placed inside a card.
+                    </Card>
+                </PageBlock>
+            </PageDetailLayout>
+        </>
+    );
+}
+```
+
+</TabItem>
+</Tabs>