@workday/canvas-kit-labs-react 15.0.0-alpha.0056-next.0 → 15.0.0-alpha.0064-next.0

package/side-panel/lib/SidePanel.tsx

@@ -0,0 +1,131 @@
+import * as React from 'react';
+import {createContainer, createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {createStencil, handleCsProp, px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+import {useSidePanelModel} from './useSidePanelModel';
+import {SidePanelToggleButton} from './SidePanelToggleButton';
+
+/**
+ * Adds the necessary props to the SidePanel container element.
+ * This includes the `id` and `aria-labelledby` attributes for accessibility.
+ */
+export const useSidePanelContainer = createElemPropsHook(useSidePanelModel)(({state, events}) => {
+  return {
+    id: state.panelId,
+    'aria-labelledby': state.labelId,
+    onTransitionEnd: events.handleAnimationEnd,
+  };
+});
+
+export type SidePanelVariant = 'standard' | 'alternate';
+
+export interface SidePanelProps {
+  /**
+   * The width of the component (in `px` if it's a `number`) when it is collapsed.
+   *
+   * @default 64
+   */
+  collapsedWidth?: number | string;
+  /**
+   * The width of the component (in `px` if it's a `number`) when it is expanded.
+   *
+   * @default 320
+   */
+  expandedWidth?: number | string;
+  /**
+   * The style variant of the side panel. 'standard' uses a lighter gray background (`system.color.bg.alt.softer`), no depth. 'alternate' uses a white background with depth (`system.color.bg.default` and level 5 depth).
+   *
+   * @default 'standard'
+   */
+  variant?: SidePanelVariant;
+  children?: React.ReactNode;
+}
+
+export const panelStencil = createStencil({
+  vars: {
+    expandedWidth: '',
+    collapsedWidth: '',
+  },
+  base: () => ({
+    overflow: 'hidden',
+    position: 'relative',
+    height: '100%',
+    outline: `${px2rem(1)} solid transparent`,
+    transition: 'width ease-out 200ms, max-width ease-out 200ms',
+  }),
+  modifiers: {
+    variant: {
+      alternate: {
+        backgroundColor: system.color.bg.default,
+        boxShadow: system.depth[5],
+      },
+      standard: {
+        backgroundColor: system.color.bg.alt.softer,
+      },
+    },
+    expanded: {
+      expanded: ({expandedWidth}) => ({
+        width: expandedWidth,
+        maxWidth: expandedWidth,
+      }),
+      collapsed: ({collapsedWidth}) => ({
+        width: collapsedWidth,
+        maxWidth: collapsedWidth,
+      }),
+      expanding: ({expandedWidth}) => ({
+        width: expandedWidth,
+        maxWidth: expandedWidth,
+      }),
+      collapsing: ({collapsedWidth}) => ({
+        width: collapsedWidth,
+        maxWidth: collapsedWidth,
+      }),
+    },
+  },
+});
+
+export const SidePanel = createContainer('section')({
+  displayName: 'SidePanel',
+  modelHook: useSidePanelModel,
+  elemPropsHook: useSidePanelContainer,
+  subComponents: {
+    /**
+     * `SidePanel.ToggleButton` is a control that toggles between expanded and collapsed states.
+     * It must be used within the `SidePanel` component as a child. For accessibility purposes,
+     * it should be the first focusable element in the panel.
+     *
+     * The button automatically receives `aria-controls`, `aria-expanded`, and `aria-labelledby`
+     * attributes from the model.
+     */
+    ToggleButton: SidePanelToggleButton,
+  },
+})<SidePanelProps>(
+  (
+    {
+      collapsedWidth = 64,
+      expandedWidth = 320,
+      variant = 'standard',
+      children,
+      ...elemProps
+    }: SidePanelProps,
+    Element,
+    model
+  ) => {
+    return (
+      <Element
+        {...handleCsProp(elemProps, [
+          panelStencil({
+            expanded: model.state.transitionState,
+            variant,
+            expandedWidth:
+              typeof expandedWidth === 'number' ? px2rem(expandedWidth) : expandedWidth,
+            collapsedWidth:
+              typeof collapsedWidth === 'number' ? px2rem(collapsedWidth) : collapsedWidth,
+          }),
+        ])}
+      >
+        {children}
+      </Element>
+    );
+  }
+);

package/side-panel/lib/SidePanelToggleButton.tsx

@@ -0,0 +1,177 @@
+import * as React from 'react';
+import {
+  createElemPropsHook,
+  createSubcomponent,
+  ExtractProps,
+} from '@workday/canvas-kit-react/common';
+import {TertiaryButton} from '@workday/canvas-kit-react/button';
+import {transformationImportIcon} from '@workday/canvas-system-icons-web';
+import {Tooltip, TooltipProps} from '@workday/canvas-kit-react/tooltip';
+import {useSidePanelModel} from './useSidePanelModel';
+import {createStencil, handleCsProp} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+export interface SidePanelToggleButtonProps extends ExtractProps<typeof TertiaryButton> {
+  /**
+   * The tooltip text to expand the side panel
+   */
+  tooltipTextExpand?: string;
+  /**
+   * The tooltip text to collapse the side panel
+   */
+  tooltipTextCollapse?: string;
+  tooltipProps?: Omit<TooltipProps, 'children'>;
+}
+
+export const sidePanelToggleButtonStencil = createStencil({
+  base: {
+    position: 'absolute',
+    top: system.space.x6,
+    width: system.space.x8,
+    insetInlineEnd: system.space.x4,
+  },
+  modifiers: {
+    state: {
+      collapsing: {
+        margin: 0,
+        transform: `scaleX(1)`,
+        ':dir(rtl)': {
+          transform: `scaleX(-1)`,
+        },
+      },
+      collapsed: {
+        margin: 'auto',
+        insetInlineStart: 0,
+        insetInlineEnd: 0,
+        transform: `scaleX(1)`,
+        ':dir(rtl)': {
+          transform: `scaleX(-1)`,
+        },
+      },
+      expanded: {
+        margin: 0,
+        transform: `scaleX(-1)`,
+        ':dir(rtl)': {
+          transform: `scaleX(1)`,
+        },
+      },
+      expanding: {
+        margin: 0,
+        transform: `scaleX(-1)`,
+        ':dir(rtl)': {
+          transform: `scaleX(1)`,
+        },
+      },
+    },
+    origin: {
+      start: {},
+      end: {
+        transform: `scaleX(1)`,
+        ':dir(rtl)': {
+          transform: `scaleX(-1)`,
+        },
+      },
+    },
+  },
+
+  compound: [
+    {
+      modifiers: {state: 'collapsed', origin: 'end'},
+      styles: {
+        transform: `scaleX(-1)`,
+        ':dir(rtl)': {
+          transform: `scaleX(1)`,
+        },
+      },
+    },
+    {
+      modifiers: {state: 'collapsing', origin: 'end'},
+      styles: {
+        transform: `scaleX(-1)`,
+        insetInlineStart: system.space.x4,
+        ':dir(rtl)': {
+          transform: `scaleX(1)`,
+          insetInlineEnd: system.space.x4,
+        },
+      },
+    },
+    {
+      modifiers: {state: 'expanded', origin: 'end'},
+      styles: {
+        transform: `scaleX(1)`,
+        insetInlineStart: system.space.x4,
+        ':dir(rtl)': {
+          transform: `scaleX(-1)`,
+          insetInlineEnd: system.space.x4,
+        },
+      },
+    },
+    {
+      modifiers: {state: 'expanding', origin: 'end'},
+      styles: {
+        transform: `scaleX(1)`,
+        insetInlineStart: system.space.x4,
+        ':dir(rtl)': {
+          transform: `scaleX(-1)`,
+          insetInlineEnd: system.space.x4,
+        },
+      },
+    },
+  ],
+});
+
+export const useSidePanelToggleButtonElemProps = createElemPropsHook(useSidePanelModel)(
+  ({state}) => {
+    return {
+      'aria-controls': state.panelId,
+      'aria-expanded': state.transitionState === 'expanded',
+      'aria-labelledby': state.labelId,
+    };
+  }
+);
+
+export const SidePanelToggleButton = createSubcomponent('button')({
+  displayName: 'SidePanel.ToggleButton',
+  modelHook: useSidePanelModel,
+  elemPropsHook: useSidePanelToggleButtonElemProps,
+})(
+  (
+    {
+      variant = undefined,
+      icon = transformationImportIcon,
+      tooltipTextExpand = 'Expand',
+      tooltipTextCollapse = 'Collapse',
+      tooltipProps,
+      ...elemProps
+    }: SidePanelToggleButtonProps,
+    Element,
+    model
+  ) => {
+    return (
+      <Tooltip
+        type="muted"
+        {...tooltipProps}
+        title={
+          model.state.transitionState === 'collapsed' ? tooltipTextExpand : tooltipTextCollapse
+        }
+      >
+        <TertiaryButton
+          icon={icon}
+          as={Element}
+          variant={variant}
+          {...handleCsProp(
+            elemProps,
+            sidePanelToggleButtonStencil({
+              state: model.state.transitionState,
+              origin: model.state.origin,
+            })
+          )}
+          onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
+            elemProps.onClick?.(event);
+            model.events.handleAnimationStart();
+          }}
+        />
+      </Tooltip>
+    );
+  }
+);

package/side-panel/lib/useSidePanelModel.ts

@@ -0,0 +1,128 @@
+import {createModelHook, useUniqueId} from '@workday/canvas-kit-react/common';
+import * as React from 'react';
+
+/**
+ * The transition states of the SidePanel during expand/collapse animations.
+ * - `expanded`: Panel is fully expanded
+ * - `expanding`: Panel is animating from collapsed to expanded
+ * - `collapsed`: Panel is fully collapsed
+ * - `collapsing`: Panel is animating from expanded to collapsed
+ */
+export type SidePanelTransitionStates = 'collapsed' | 'collapsing' | 'expanded' | 'expanding';
+
+export const useSidePanelModel = createModelHook({
+  defaultConfig: {
+    /**
+     * The initial transition state of the SidePanel.
+     * @default 'expanded'
+     */
+    initialTransitionState: 'expanded' as SidePanelTransitionStates,
+    /**
+     * Which side the SidePanel originates from. Uses logical properties for RTL support.
+     * - `start`: Left side in LTR, right side in RTL
+     * - `end`: Right side in LTR, left side in RTL
+     * @default 'start'
+     */
+    origin: 'start' as 'start' | 'end',
+    /**
+     * The unique ID for the panel element. If not provided, a unique ID will be generated.
+     * This ID is used for the `aria-controls` attribute on the toggle button.
+     */
+    panelId: '',
+    /**
+     * The unique ID for the panel's label element. If not provided, a unique ID will be generated.
+     * This ID is used for the `aria-labelledby` attribute on both the panel and toggle button.
+     */
+    labelId: '',
+    /**
+     * Callback fired when the SidePanel's transition state changes.
+     * Use this to react to state changes including animation states.
+     * @param state The new transition state
+     */
+    onStateTransition(state: SidePanelTransitionStates) {
+      // no-op by default
+    },
+  },
+})(config => {
+  const panelId = useUniqueId(config.panelId);
+  const labelId = useUniqueId(config.labelId);
+  const [transitionState, setTransitionStateInternal] = React.useState<SidePanelTransitionStates>(
+    config.initialTransitionState
+  );
+
+  // Wrap setTransitionState to call the onStateTransition callback
+  const setTransitionState = React.useCallback(
+    (newState: SidePanelTransitionStates) => {
+      setTransitionStateInternal(newState);
+      config.onStateTransition(newState);
+    },
+    [config]
+  );
+
+  const state = {
+    ...config,
+    /**
+     * The unique ID for the panel element. Used for `aria-controls` on the toggle button.
+     */
+    panelId,
+    /**
+     * The unique ID for the panel's label element. Used for `aria-labelledby` on the panel
+     * and toggle button to provide an accessible name.
+     */
+    labelId,
+    /**
+     * The current transition state of the SidePanel. This tracks both the expanded/collapsed
+     * state and the animation states (expanding/collapsing).
+     */
+    transitionState,
+  };
+
+  const events = {
+    /**
+     * Expand the SidePanel. This sets the state directly to `expanded` without animation.
+     * For animated expansion, use the toggle button which triggers `setExpandingState`.
+     */
+    expand() {
+      setTransitionState('expanded');
+    },
+
+    /**
+     * Collapse the SidePanel. This sets the state directly to `collapsed` without animation.
+     * For animated collapse, use the toggle button which triggers `setCollapsingState`.
+     */
+    collapse() {
+      setTransitionState('collapsed');
+    },
+
+    /**
+     * Handler for the CSS transition end event. This should be called when the width
+     * transition completes to finalize the state from `expanding` to `expanded` or
+     * from `collapsing` to `collapsed`.
+     */
+    handleAnimationEnd(event: React.TransitionEvent<HTMLDivElement>) {
+      if (event.propertyName === 'width') {
+        if (transitionState === 'expanding') {
+          setTransitionState('expanded');
+        } else if (transitionState === 'collapsing') {
+          setTransitionState('collapsed');
+        }
+      }
+      return event;
+    },
+
+    /**
+     * Triggers the start of a transition animation. This toggles between expanding
+     * and collapsing states based on the current state.
+     */
+    handleAnimationStart() {
+      if (transitionState === 'collapsed' || transitionState === 'collapsing') {
+        setTransitionState('expanding');
+      } else if (transitionState === 'expanded' || transitionState === 'expanding') {
+        setTransitionState('collapsing');
+      }
+      return undefined;
+    },
+  };
+
+  return {state, events};
+});

package/side-panel/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/commonjs/side-panel",
+  "module": "../dist/es6/side-panel",
+  "sideEffects": false,
+  "types": "../dist/es6/side-panel"
+}