@pharos-ds/core 1.0.9 → 1.0.10-canary.8c2af6f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pharos-ds/core",
-  "version": "1.0.9",
+  "version": "1.0.10-canary.8c2af6f",
   "displayName": "Pharos Core",
   "description": "Pharos component library. Accessible, themeable React components with spacing, dark mode, and StyleX styling.",
   "author": "Caio Silvestre",

package/src/SideNav/SideNav.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
       {className: 'pharos-side-nav-section', states: ['collapsed']},
     ],
   },
-  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',
+  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode: the collapsed rail shows only item icons, footerIcons, and the collapse button (footer is hidden).',
   props: [
     {
       name: 'header',
@@ -71,7 +71,7 @@ export const docs = {
     {
       name: 'footer',
       type: 'ReactNode',
-      description: 'Footer area above the icon bar.',
+      description: 'Footer area above the icon bar. Hidden while the SideNav is collapsed to the icon rail, since full-width content does not fit; put actions that must stay reachable in footerIcons.',
       slotElements: [
         {
           __element: 'Text',
@@ -85,7 +85,7 @@ export const docs = {
     {
       name: 'footerIcons',
       type: 'ReactNode',
-      description: 'Footer icon bar.',
+      description: 'Footer icon bar. Stays visible in the collapsed rail, next to the collapse button.',
       slotElements: [
         {
           __element: 'Icon',
@@ -99,7 +99,7 @@ export const docs = {
     {
       name: 'collapsible',
       type: 'boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string }',
-      description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
+      description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel). When collapsed, the rail shows item icons only (items without icons are hidden), keeps footerIcons and the collapse button, and does not render footer. Read the state inside the nav with useSideNavCollapse().',
       default: 'false',
     },
     {
@@ -131,6 +131,9 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+      {guidance: true, description: 'Make the SideNav of an app shell collapsible so users can fold it into an icon rail; control it with collapsible={{isCollapsed, onCollapsedChange}} to persist the choice.'},
+      {guidance: true, description: 'Give every top-level SideNavItem an icon: the collapsed rail hides items without one. Swap the header for a compact mark (e.g. a symbol logo) by reading useSideNavCollapse().isCollapsed.'},
+      {guidance: true, description: 'Put actions that must stay reachable in the rail (settings, account, theme, sign out) in footerIcons as icon buttons; footer is hidden while collapsed, so use it only for full-width extras such as promo cards or density controls.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
     ],
@@ -150,6 +153,9 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+      {guidance: true, description: 'Make the SideNav of an app shell collapsible so users can fold it into an icon rail; control it with collapsible={{isCollapsed, onCollapsedChange}} to persist the choice.'},
+      {guidance: true, description: 'Give every top-level SideNavItem an icon: the collapsed rail hides items without one. Swap the header for a compact mark (e.g. a symbol logo) by reading useSideNavCollapse().isCollapsed.'},
+      {guidance: true, description: 'Put actions that must stay reachable in the rail (settings, account, theme, sign out) in footerIcons as icon buttons; footer is hidden while collapsed, so use it only for full-width extras such as promo cards or density controls.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
     ],
@@ -169,6 +175,9 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+      {guidance: true, description: 'Make the SideNav of an app shell collapsible so users can fold it into an icon rail; control it with collapsible={{isCollapsed, onCollapsedChange}} to persist the choice.'},
+      {guidance: true, description: 'Give every top-level SideNavItem an icon: the collapsed rail hides items without one. Swap the header for a compact mark (e.g. a symbol logo) by reading useSideNavCollapse().isCollapsed.'},
+      {guidance: true, description: 'Put actions that must stay reachable in the rail (settings, account, theme, sign out) in footerIcons as icon buttons; footer is hidden while collapsed, so use it only for full-width extras such as promo cards or density controls.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
     ],

package/src/SideNav/SideNav.test.tsx

@@ -183,6 +183,71 @@ describe('SideNav', () => {
     expect(nav.children).toHaveLength(1);
   });
 
+  describe('footer in the collapsed rail', () => {
+    it('hides footer but keeps footerIcons and the collapse button when collapsed', () => {
+      render(
+        <SideNav
+          collapsible={{defaultIsCollapsed: true}}
+          footer={<span data-testid="footer">Footer</span>}
+          footerIcons={<span data-testid="icons">Icons</span>}>
+          <SideNavItem label="Dashboard" icon={StubIcon} />
+        </SideNav>,
+      );
+
+      expect(screen.queryByTestId('footer')).not.toBeInTheDocument();
+      expect(screen.getByTestId('icons')).toBeInTheDocument();
+      expect(
+        screen.getByRole('button', {name: 'Expand sidebar'}),
+      ).toBeInTheDocument();
+    });
+
+    it('shows footer again after expanding the rail', async () => {
+      const user = userEvent.setup();
+      render(
+        <SideNav
+          collapsible={{defaultIsCollapsed: true}}
+          footer={<span data-testid="footer">Footer</span>}>
+          <SideNavItem label="Dashboard" icon={StubIcon} />
+        </SideNav>,
+      );
+
+      expect(screen.queryByTestId('footer')).not.toBeInTheDocument();
+      await user.click(screen.getByRole('button', {name: 'Expand sidebar'}));
+      expect(screen.getByTestId('footer')).toBeInTheDocument();
+    });
+
+    it('does not leave an empty footer container when only footer is set and the rail has no button', () => {
+      render(
+        <SideNav
+          data-testid="nav"
+          collapsible={{isCollapsed: true, hasButton: false}}
+          footer={<span data-testid="footer">Footer</span>}>
+          Content
+        </SideNav>,
+      );
+
+      expect(screen.queryByTestId('footer')).not.toBeInTheDocument();
+      expect(screen.getByTestId('nav').children).toHaveLength(1);
+    });
+
+    it('keeps rendering footer when the SideNav is expanded or not collapsible', () => {
+      const {unmount} = render(
+        <SideNav collapsible footer={<span data-testid="footer">Footer</span>}>
+          Content
+        </SideNav>,
+      );
+      expect(screen.getByTestId('footer')).toBeInTheDocument();
+      unmount();
+
+      render(
+        <SideNav footer={<span data-testid="footer">Footer</span>}>
+          Content
+        </SideNav>,
+      );
+      expect(screen.getByTestId('footer')).toBeInTheDocument();
+    });
+  });
+
   it('fires a consumer onClick on the collapse button in addition to toggling', async () => {
     const user = userEvent.setup();
     const onClick = vi.fn();

package/src/SideNav/SideNav.tsx

@@ -10,6 +10,8 @@
  *
  * Sidebar navigation container with five zones: header + topContent (sticky together),
  * children (scrollable), footer, and footerIcons (sticky bottom).
+ * When collapsed to the icon rail, `footer` is hidden; `footerIcons` and the
+ * collapse button remain.
  *
  * Supports optional resize via drag handle at the inline-end edge.
  *
@@ -212,7 +214,9 @@ export interface SideNavProps extends BaseProps<HTMLElement> {
    */
   children: ReactNode;
   /**
-   * Footer area above icon bar (e.g., promo cards).
+   * Footer area above icon bar (e.g., promo cards). Not rendered while the
+   * sidebar is collapsed to the icon rail (full-width content doesn't fit);
+   * use `footerIcons` for actions that must stay visible in the rail.
    */
   footer?: ReactNode;
   /**
@@ -484,7 +488,11 @@ export function SideNav({
   // Default mode — full sidebar
   // =========================================================================
   const hasStickyTop = !!(header || topContent);
-  const hasStickyBottom = !!(footer || footerIcons);
+  // In the collapsed rail, `footer` is not rendered: its content is laid out
+  // full-width (promo cards, segmented controls, account blocks) and doesn't
+  // fit the icon-only rail. `footerIcons` and the collapse button stay.
+  const visibleFooter = collapsed ? null : footer;
+  const hasStickyBottom = !!(visibleFooter || footerIcons);
   // The built-in collapse button only renders when collapse is enabled and it
   // hasn't been opted out via `collapsible.hasButton: false` (e.g. when the
   // consumer places a SideNavCollapseButton in the header instead).
@@ -537,7 +545,7 @@ export function SideNav({
             styles.stickyBottom,
             collapsed && styles.stickyBottomCollapsed,
           )}>
-          {footer}
+          {visibleFooter}
           <div
             {...stylex.props(
               styles.footerRow,