@dt-dds/react-sidebar 1.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @dt-dds/react-sidebar
+
+## 1.0.0-beta.1
+
+### Minor Changes
+
+- feat: add sidebar compound component

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daimler Truck AG.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# Sidebar Package
+
+A compound component for building navigation sidebars with collapsible sections, nested items, and responsive behavior.
+
+## Usage
+
+```jsx
+import { useTheme } from '@emotion/react';
+import { Sidebar, useSidebar } from '@dt-dds/react-sidebar';
+import { Icon } from '@dt-dds/react-icon';
+
+export const App = () => {
+  const theme = useTheme();
+
+  const { isExpanded, toggleSidebar } = useSidebar({ isExpanded: true });
+
+  return (
+    <Sidebar isExpanded={isExpanded} onToggle={toggleSidebar}>
+      <Sidebar.Header show={`(max-width: ${theme.breakpoints.mq3}px)`}>
+        <Sidebar.Item>
+          <Sidebar.Toggle />
+          <span>App Name</span>
+        </Sidebar.Item>
+      </Sidebar.Header>
+
+      <Sidebar.Divider show={`(max-width: ${theme.breakpoints.mq3}px)`} />
+
+      <Sidebar.Content>
+        <Sidebar.Section title='Section One'>
+          <Sidebar.Item href='/'>
+            <Icon code='dashboard' />
+            Menu Item
+          </Sidebar.Item>
+          <Sidebar.Item href='/'>
+            <Icon code='analytics' />
+            Menu Item
+            <Sidebar.SubList>
+              <Sidebar.Item href='/'>Nested Menu Item</Sidebar.Item>
+              <Sidebar.Item href='/'>Nested Menu Item</Sidebar.Item>
+            </Sidebar.SubList>
+          </Sidebar.Item>
+        </Sidebar.Section>
+      </Sidebar.Content>
+
+      <Sidebar.Divider />
+
+      <Sidebar.Footer>
+        <Sidebar.Item href='/settings'>
+          <Icon code='settings' />
+          Settings
+        </Sidebar.Item>
+      </Sidebar.Footer>
+
+      <Sidebar.Divider hide={`(max-width: ${theme.breakpoints.mq3}px)`} />
+
+      <Sidebar.Footer hide={`(max-width: ${theme.breakpoints.mq3}px)`}>
+        <Sidebar.Item>
+          <Sidebar.Toggle />
+          <span>Collapse</span>
+        </Sidebar.Item>
+      </Sidebar.Footer>
+    </Sidebar>
+  );
+};
+```
+
+## API
+
+### Sidebar
+
+| Property     | Type                          | Default  | Description                       |
+| ------------ | ----------------------------- | -------- | --------------------------------- |
+| `isExpanded` | `boolean`                     | required | Controls expanded/collapsed state |
+| `onToggle`   | `(expanded: boolean) => void` | -        | Callback when toggle is triggered |
+| `placement`  | `'left' \| 'right'`           | `'left'` | Desktop sidebar position          |
+| `offsetTop`  | `number`                      | `0`      | Top offset in pixels              |
+| `ariaLabel`  | `string`                      | -        | Accessibility label               |
+
+### Sidebar.Item
+
+| Property          | Type                          | Default | Description                       |
+| ----------------- | ----------------------------- | ------- | --------------------------------- |
+| `href`            | `string`                      | -       | Navigation URL                    |
+| `defaultExpanded` | `boolean`                     | `false` | Initial expanded state (SubList)  |
+| `expanded`        | `boolean`                     | -       | Controlled expanded state         |
+| `onToggle`        | `(expanded: boolean) => void` | -       | Callback when item is toggled     |
+| `children`        | `ReactNode`                   | -       | Item content and optional SubList |
+
+### Sidebar.Section
+
+| Property   | Type        | Default | Description   |
+| ---------- | ----------- | ------- | ------------- |
+| `title`    | `string`    | -       | Section title |
+| `children` | `ReactNode` | -       | Section items |
+
+### Sidebar.SubList
+
+Wrapper for nested `Sidebar.Item` elements. Auto-expands when a child item is active.
+
+### Sidebar.Header / Sidebar.Footer
+
+Fixed position sections at top/bottom of the sidebar.
+
+### Sidebar.Content
+
+Scrollable content area between header and footer.
+
+### Sidebar.Toggle
+
+Button that triggers `onToggle`.
+
+### Sidebar.Divider
+
+Visual separator between sections.
+
+## Hooks
+
+### useSidebar
+
+Standalone state management hook.
+
+```jsx
+const { isExpanded, setIsExpanded, toggleSidebar } = useSidebar({
+  isExpanded: true,
+});
+```
+
+## Custom Link Components
+
+Supports custom link components (React Router, Next.js, etc.):
+
+```jsx
+<Sidebar.Item>
+  <Link to='/dashboard'>
+    <Icon code='dashboard' />
+    Dashboard
+  </Link>
+</Sidebar.Item>
+```
+
+## Stack
+
+- [TypeScript](https://www.typescriptlang.org/) for static type checking
+- [React](https://reactjs.org/) — JavaScript library for user interfaces
+- [Emotion](https://emotion.sh/docs/introduction) — for writing css styles with JavaScript
+- [Storybook](https://storybook.js.org/) — UI component environment powered by Vite
+- [Jest](https://jestjs.io/) - JavaScript Testing Framework
+- [React Testing Library](https://testing-library.com/) - to test UI components in a user-centric way
+- [ESLint](https://eslint.org/) for code linting
+- [Prettier](https://prettier.io) for code formatting
+- [Tsup](https://github.com/egoist/tsup) — TypeScript bundler powered by esbuild
+- [Yarn](https://yarnpkg.com/) from managing packages
+
+## Commands
+
+- `yarn build` - Build the package
+- `yarn dev` - Run the package locally
+- `yarn lint` - Lint all files within this package
+- `yarn test` - Run all unit tests
+- `yarn test:report` - Open the test coverage report
+- `yarn test:update:snapshot` - Run all unit tests and update the snapshot
+
+## Compilation
+
+Running `yarn build` from the root of the package will use [tsup](https://tsup.egoist.dev/) to compile the raw TypeScript and React code to plain JavaScript.
+
+The `/dist` folder contains the compiled output.
+
+```bash
+sidebar
+└── dist
+    ├── index.d.ts  <-- Types
+    ├── index.js    <-- CommonJS version
+    └── index.mjs   <-- ES Modules version
+    ...
+```
+
+## Versioning
+
+Follows [semantic versioning](https://semver.org/)
+
+## &copy; License
+
+Licensed under [MIT License](LICENSE.md)

package/dist/index.d.mts

@@ -0,0 +1,93 @@
+import { Theme } from '@dt-dds/themes';
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ResponsiveProps, BaseProps } from '@dt-dds/react-core';
+
+interface SidebarDividerProps extends ResponsiveProps, BaseProps, HTMLAttributes<HTMLHRElement> {
+}
+
+interface SidebarSectionProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    title?: string;
+    children: ReactNode;
+}
+
+interface SidebarHeaderProps extends ResponsiveProps, BaseProps, HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+
+interface SidebarFooterProps extends ResponsiveProps, BaseProps, HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+
+interface SidebarItemProps extends BaseProps, Omit<HTMLAttributes<HTMLLIElement>, 'onClick'> {
+    href?: string;
+    defaultExpanded?: boolean;
+    expanded?: boolean;
+    onToggle?: (expanded: boolean) => void;
+    children: ReactNode;
+}
+
+interface SidebarSubListProps extends BaseProps, HTMLAttributes<HTMLUListElement> {
+    children: ReactNode;
+}
+
+interface SidebarContentProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+
+interface SidebarToggleProps {
+    onClick?: () => void;
+}
+
+type SidebarPlacement = 'left' | 'right';
+
+interface SidebarProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    ariaLabel?: string;
+    isExpanded: boolean;
+    offsetTop?: number;
+    placement?: SidebarPlacement;
+    onToggle?: (expanded: boolean) => void;
+}
+declare const Sidebar: {
+    ({ dataTestId, offsetTop, children, ariaLabel, style, isExpanded, placement, onToggle, ...rest }: SidebarProps): react_jsx_runtime.JSX.Element;
+    Content: {
+        ({ children, dataTestId, style, ...rest }: SidebarContentProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Divider: react.ComponentType<SidebarDividerProps>;
+    Section: {
+        ({ title, children, dataTestId, style, ...rest }: SidebarSectionProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Item: {
+        ({ href, defaultExpanded, expanded: controlledExpanded, onToggle, children, dataTestId, style, ...rest }: SidebarItemProps): react_jsx_runtime.JSX.Element | null;
+        displayName: string;
+    };
+    SubList: {
+        ({ children, dataTestId, style, ...rest }: SidebarSubListProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Header: react.ComponentType<SidebarHeaderProps>;
+    Footer: react.ComponentType<SidebarFooterProps>;
+    Toggle: {
+        ({ onClick }: SidebarToggleProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+};
+
+interface UseSidebarOptions {
+    isExpanded?: boolean;
+}
+declare const useSidebar: (options?: UseSidebarOptions) => {
+    isExpanded: boolean;
+    setIsExpanded: (expanded: boolean) => void;
+    toggleSidebar: () => void;
+};
+
+declare module '@emotion/react' {
+    interface Theme extends Theme {
+    }
+}
+
+export { Sidebar, type SidebarProps, type UseSidebarOptions, useSidebar };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { Theme } from '@dt-dds/themes';
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ResponsiveProps, BaseProps } from '@dt-dds/react-core';
+
+interface SidebarDividerProps extends ResponsiveProps, BaseProps, HTMLAttributes<HTMLHRElement> {
+}
+
+interface SidebarSectionProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    title?: string;
+    children: ReactNode;
+}
+
+interface SidebarHeaderProps extends ResponsiveProps, BaseProps, HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+
+interface SidebarFooterProps extends ResponsiveProps, BaseProps, HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+
+interface SidebarItemProps extends BaseProps, Omit<HTMLAttributes<HTMLLIElement>, 'onClick'> {
+    href?: string;
+    defaultExpanded?: boolean;
+    expanded?: boolean;
+    onToggle?: (expanded: boolean) => void;
+    children: ReactNode;
+}
+
+interface SidebarSubListProps extends BaseProps, HTMLAttributes<HTMLUListElement> {
+    children: ReactNode;
+}
+
+interface SidebarContentProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+
+interface SidebarToggleProps {
+    onClick?: () => void;
+}
+
+type SidebarPlacement = 'left' | 'right';
+
+interface SidebarProps extends BaseProps, HTMLAttributes<HTMLElement> {
+    ariaLabel?: string;
+    isExpanded: boolean;
+    offsetTop?: number;
+    placement?: SidebarPlacement;
+    onToggle?: (expanded: boolean) => void;
+}
+declare const Sidebar: {
+    ({ dataTestId, offsetTop, children, ariaLabel, style, isExpanded, placement, onToggle, ...rest }: SidebarProps): react_jsx_runtime.JSX.Element;
+    Content: {
+        ({ children, dataTestId, style, ...rest }: SidebarContentProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Divider: react.ComponentType<SidebarDividerProps>;
+    Section: {
+        ({ title, children, dataTestId, style, ...rest }: SidebarSectionProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Item: {
+        ({ href, defaultExpanded, expanded: controlledExpanded, onToggle, children, dataTestId, style, ...rest }: SidebarItemProps): react_jsx_runtime.JSX.Element | null;
+        displayName: string;
+    };
+    SubList: {
+        ({ children, dataTestId, style, ...rest }: SidebarSubListProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Header: react.ComponentType<SidebarHeaderProps>;
+    Footer: react.ComponentType<SidebarFooterProps>;
+    Toggle: {
+        ({ onClick }: SidebarToggleProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+};
+
+interface UseSidebarOptions {
+    isExpanded?: boolean;
+}
+declare const useSidebar: (options?: UseSidebarOptions) => {
+    isExpanded: boolean;
+    setIsExpanded: (expanded: boolean) => void;
+    toggleSidebar: () => void;
+};
+
+declare module '@emotion/react' {
+    interface Theme extends Theme {
+    }
+}
+
+export { Sidebar, type SidebarProps, type UseSidebarOptions, useSidebar };