@ngrr/ds 0.1.12 → 0.1.13

package/AGENTS.md

@@ -448,4 +448,157 @@ Either populate with real, meaningful content or hide the slot entirely.
 2. Identify all Figma variants → TypeScript props
 3. Identify all tokens needed (colour, typography, spacing, sizing)
 4. Implement component → stories → tests in that order
-5. Export from component `index.ts` and from `src/index.ts`
+5. Export from component `index.ts` and from `src/index.ts`
+
+---
+
+## Consuming the Package — Layout & Navigation
+
+> This section is for AI agents building apps with `@ngrr/ds`, not for building the library itself.
+
+### Setup — mandatory CSS imports
+```tsx
+// main.tsx — must be first, before any other imports
+import '@ngrr/ds/style.css'
+import '@ngrr/ds/tokens.css'
+```
+
+### Required CSS on the host app
+```css
+html, body { margin: 0; height: 100%; }
+#root { min-height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
+```
+
+---
+
+### AppShell — mandatory root layout
+
+`AppShell` is the only permitted root layout wrapper. Every page must be inside it. Do not invent wrapper divs or custom layouts.
+```tsx
+import { AppShell, Navbar, Sidebar, Button, SearchBar, Avatar } from '@ngrr/ds';
+// Icons come from lucide-react — install separately: npm install lucide-react
+import { LayoutDashboard, FolderKanban, CheckSquare, Users, FileText, Settings } from 'lucide-react';
+
+<AppShell
+  header={
+    <Navbar
+      title="Dashboard"
+      rightActions={<Button variant="primary" label="New project" />}
+    />
+  }
+  sidebar={
+    <Sidebar
+      selectorProps={{
+        label: 'WorkScope',
+        avatarProps: {
+          size: 'xs',
+          variant: 'organization',
+          fill: 'initials',
+          initials: 'WS',
+          name: 'WorkScope',
+        },
+      }}
+      showSearch
+      searchSlot={<SearchBar placeholder="Search" />}
+      sections={[
+        {
+          id: 'main',
+          items: [
+            { id: 'dashboard', label: 'Dashboard', icon: <LayoutDashboard size={16} />, selected: true, onClick: () => {} },
+            { id: 'projects', label: 'Projects', icon: <FolderKanban size={16} />, onClick: () => {} },
+            { id: 'tasks', label: 'Tasks', icon: <CheckSquare size={16} />, onClick: () => {} },
+            { id: 'people', label: 'People', icon: <Users size={16} />, onClick: () => {} },
+            { id: 'notes', label: 'Notes', icon: <FileText size={16} />, onClick: () => {} },
+          ],
+        },
+      ]}
+      bottomContent={
+        <>
+          <SidebarMenuSelector
+            variant="full"
+            label="Settings"
+            showIcon
+            icon={<Settings size={16} />}
+            onClick={() => {}}
+          />
+          <SidebarMenuSelector
+            variant="full"
+            label="User Name"
+            showAvatar
+            avatarProps={{ size: 'xs', fill: 'initials', initials: 'UN', name: 'User Name' }}
+            onClick={() => {}}
+          />
+        </>
+      }
+    />
+  }
+>
+  {/* page content goes here */}
+</AppShell>
+```
+
+**AppShell props:**
+- `header` — `<Navbar />` only
+- `sidebar` — `<Sidebar />` only. Never pass `collapsed` manually — AppShell injects it automatically
+- `children` — main page content
+- `rightPanel` — optional, omit if not needed
+- `footer` — optional, omit if not needed
+
+**Forbidden:**
+- Do not wrap AppShell in any other layout element
+- Do not add sidebar items beyond what is specified
+- Do not invent extra sections, items, or nav elements
+
+---
+
+### Navbar props
+- `variant` — `'title'` (default) for top-level pages | `'breadcrumbs'` for detail views only
+- `title` — page title, sentence case
+- `rightActions` — primary CTA button, rightmost position
+- `leftActions` — secondary actions on the left, omit if not needed
+- `onBackClick` — only used with `variant="breadcrumbs"`
+- `breadcrumbItems` — required only when `variant="breadcrumbs"`
+
+**Rules:**
+- Never show a back arrow on top-level pages (Dashboard, Projects, Tasks, People, Notes)
+- Back arrow only on detail views using `variant="breadcrumbs"`
+- Primary CTA always in `rightActions`
+
+---
+
+### Sidebar props
+- `sections` — required. Only include sections explicitly specified. Never invent extra items.
+- `selectorProps` — workspace selector at the top. Always set `label` and `avatarProps`.
+- `showSearch` — set to `true` to show the search bar
+- `searchSlot` — pass a `<SearchBar />` component when `showSearch` is true
+- `bottomContent` — use for Settings and User Name, pinned to bottom with a divider. Always include these two items.
+- Never pass `collapsed` — AppShell controls it automatically
+
+**SidebarMenuItem shape:**
+```ts
+{
+  id: string;
+  label: string;           // sentence case always
+  icon?: React.ReactNode;  // lucide-react icon at size={16}
+  selected?: boolean;      // true only for the active page
+  onClick?: () => void;
+  showBadge?: boolean;
+  badgeCount?: number;
+  badgeVariant?: BadgeVariant;
+  showAvatar?: boolean;
+  avatarProps?: AvatarProps;
+}
+```
+
+---
+
+### Hard rules — always follow
+- `AppShell` is always the root — no exceptions
+- `DataTable` must never be wrapped in a `Card`
+- No back arrow on top-level pages: Dashboard, Projects, Tasks, People, Notes
+- CTA hierarchy: Primary (object creation, rightmost in Navbar) → Secondary → Ghost (Export, Share, Edit)
+- All labels and copy: sentence case always ("New project" not "New Project")
+- Icons: from `lucide-react` — install with `npm install lucide-react`
+- Tag variants: `success` = completed, `progress` = in progress, `warning` = at risk, `neutral` = not started
+- Settings and User Name always pinned to sidebar bottom via `bottomContent`
+- Sidebar always full viewport height — guaranteed by AppShell CSS rules above

package/AI.md

@@ -1973,4 +1973,159 @@ export const DisabledVariant: Story = {
 ---
 
 *Generated from DS-Nagarro design system docs. Last updated: 2026-03-10.*
-*Source files: `docs/foundations.md`, `docs/ds-guidelines.md`, and all component docs in `docs/`.*
+*Source files: `docs/foundations.md`, `docs/ds-guidelines.md`, and all component docs in `docs/`.*
+
+---
+
+---
+
+## Consuming the Package — Layout & Navigation
+
+> This section is for AI agents building apps with `@ngrr/ds`, not for building the library itself.
+
+### Setup — mandatory CSS imports
+```tsx
+// main.tsx — must be first, before any other imports
+import '@ngrr/ds/style.css'
+import '@ngrr/ds/tokens.css'
+```
+
+### Required CSS on the host app
+```css
+html, body { margin: 0; height: 100%; }
+#root { min-height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
+```
+
+---
+
+### AppShell — mandatory root layout
+
+`AppShell` is the only permitted root layout wrapper. Every page must be inside it. Do not invent wrapper divs or custom layouts.
+```tsx
+import { AppShell, Navbar, Sidebar, Button, SearchBar, Avatar } from '@ngrr/ds';
+// Icons come from lucide-react — install separately: npm install lucide-react
+import { LayoutDashboard, FolderKanban, CheckSquare, Users, FileText, Settings } from 'lucide-react';
+
+<AppShell
+  header={
+    <Navbar
+      title="Dashboard"
+      rightActions={<Button variant="primary" label="New project" />}
+    />
+  }
+  sidebar={
+    <Sidebar
+      selectorProps={{
+        label: 'WorkScope',
+        avatarProps: {
+          size: 'xs',
+          variant: 'organization',
+          fill: 'initials',
+          initials: 'WS',
+          name: 'WorkScope',
+        },
+      }}
+      showSearch
+      searchSlot={<SearchBar placeholder="Search" />}
+      sections={[
+        {
+          id: 'main',
+          items: [
+            { id: 'dashboard', label: 'Dashboard', icon: <LayoutDashboard size={16} />, selected: true, onClick: () => {} },
+            { id: 'projects', label: 'Projects', icon: <FolderKanban size={16} />, onClick: () => {} },
+            { id: 'tasks', label: 'Tasks', icon: <CheckSquare size={16} />, onClick: () => {} },
+            { id: 'people', label: 'People', icon: <Users size={16} />, onClick: () => {} },
+            { id: 'notes', label: 'Notes', icon: <FileText size={16} />, onClick: () => {} },
+          ],
+        },
+      ]}
+      bottomContent={
+        <>
+          <SidebarMenuSelector
+            variant="full"
+            label="Settings"
+            showIcon
+            icon={<Settings size={16} />}
+            onClick={() => {}}
+          />
+          <SidebarMenuSelector
+            variant="full"
+            label="User Name"
+            showAvatar
+            avatarProps={{ size: 'xs', fill: 'initials', initials: 'UN', name: 'User Name' }}
+            onClick={() => {}}
+          />
+        </>
+      }
+    />
+  }
+>
+  {/* page content goes here */}
+</AppShell>
+```
+
+**AppShell props:**
+- `header` — `<Navbar />` only
+- `sidebar` — `<Sidebar />` only. Never pass `collapsed` manually — AppShell injects it automatically
+- `children` — main page content
+- `rightPanel` — optional, omit if not needed
+- `footer` — optional, omit if not needed
+
+**Forbidden:**
+- Do not wrap AppShell in any other layout element
+- Do not add sidebar items beyond what is specified
+- Do not invent extra sections, items, or nav elements
+
+---
+
+### Navbar props
+- `variant` — `'title'` (default) for top-level pages | `'breadcrumbs'` for detail views only
+- `title` — page title, sentence case
+- `rightActions` — primary CTA button, rightmost position
+- `leftActions` — secondary actions on the left, omit if not needed
+- `onBackClick` — only used with `variant="breadcrumbs"`
+- `breadcrumbItems` — required only when `variant="breadcrumbs"`
+
+**Rules:**
+- Never show a back arrow on top-level pages (Dashboard, Projects, Tasks, People, Notes)
+- Back arrow only on detail views using `variant="breadcrumbs"`
+- Primary CTA always in `rightActions`
+
+---
+
+### Sidebar props
+- `sections` — required. Only include sections explicitly specified. Never invent extra items.
+- `selectorProps` — workspace selector at the top. Always set `label` and `avatarProps`.
+- `showSearch` — set to `true` to show the search bar
+- `searchSlot` — pass a `<SearchBar />` component when `showSearch` is true
+- `bottomContent` — use for Settings and User Name, pinned to bottom with a divider. Always include these two items.
+- Never pass `collapsed` — AppShell controls it automatically
+
+**SidebarMenuItem shape:**
+```ts
+{
+  id: string;
+  label: string;           // sentence case always
+  icon?: React.ReactNode;  // lucide-react icon at size={16}
+  selected?: boolean;      // true only for the active page
+  onClick?: () => void;
+  showBadge?: boolean;
+  badgeCount?: number;
+  badgeVariant?: BadgeVariant;
+  showAvatar?: boolean;
+  avatarProps?: AvatarProps;
+}
+```
+
+---
+
+### Hard rules — always follow
+- `AppShell` is always the root — no exceptions
+- `DataTable` must never be wrapped in a `Card`
+- No back arrow on top-level pages: Dashboard, Projects, Tasks, People, Notes
+- CTA hierarchy: Primary (object creation, rightmost in Navbar) → Secondary → Ghost (Export, Share, Edit)
+- All labels and copy: sentence case always ("New project" not "New Project")
+- Icons: from `lucide-react` — install with `npm install lucide-react`
+- Tag variants: `success` = completed, `progress` = in progress, `warning` = at risk, `neutral` = not started
+- Settings and User Name always pinned to sidebar bottom via `bottomContent`
+- Sidebar always full viewport height — guaranteed by AppShell CSS rules above

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngrr/ds",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "main": "./dist/ds-nagarro.umd.js",
   "module": "./dist/ds-nagarro.es.js",
   "types": "./dist/index.d.ts",
@@ -43,6 +43,7 @@
     "@lexical/react": "^0.41.0",
     "@lexical/rich-text": "^0.41.0",
     "@lexical/selection": "^0.41.0",
+    "@ngrr/ds": "^0.1.12",
     "@react-spring/web": "^9.7.5",
     "@visx/axis": "^3.12.0",
     "@visx/brush": "^3.12.0",