@fortanix/baklava 1.0.0-beta-20241114

package/src/components/util/Popover/Popover.tsx

@@ -0,0 +1,219 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import * as React from 'react';
+
+import {
+  type Side,
+  type Alignment,
+  type Placement,
+  autoUpdate,
+  offset,
+  shift,
+  limitShift,
+  flip,
+  arrow,
+  type ElementProps,
+  type UseFloatingOptions,
+  type FlipOptions,
+  type FloatingContext,
+  useFloating,
+  useRole,
+  useFocus,
+  useClick,
+  useDismiss,
+  useDelayGroup,
+  useHover,
+  useInteractions,
+  useTransitionStatus,
+  hide,
+} from '@floating-ui/react';
+
+
+export { type Placement };
+
+export type UsePopoverOptions = {
+  floatingUiOptions?: UseFloatingOptions,
+  floatingUiFlipOptions?: FlipOptions,
+  floatingUiInteractions?: (context: FloatingContext) => Array<undefined | ElementProps>,
+  action?: undefined | 'hover' | 'click',
+  placement?: undefined | Placement,
+  offset?: undefined | number,
+  enablePreciseTracking?: boolean, // Enable more precise tracking of the anchor, at the cost of performance
+  boundary?: undefined | Element,
+  arrowRef?: React.RefObject<Element>, // Reference to the arrow element, if any
+  hasDelayGroup?: undefined | boolean,
+};
+export const usePopover = (options: UsePopoverOptions = {}) => {
+  const optionsWithDefaults = {
+    ...options,
+    floatingUiOptions: options.floatingUiOptions ?? {},
+    floatingUiFlipOptions: options.floatingUiFlipOptions ?? {},
+    floatingUiInteractions: options.floatingUiInteractions ?? (() => []),
+    action: options.action ?? 'click',
+    placement: options.placement ?? 'top',
+    offset: options.offset ?? 0,
+    enablePreciseTracking: options.enablePreciseTracking ?? false,
+    arrowRef: options.arrowRef ?? null,
+    hasDelayGroup: options.hasDelayGroup ?? false,
+  };
+  
+  // Memoize `action` to make sure it doesn't change, to prevent conditional use of hooks
+  const action = React.useMemo(() => optionsWithDefaults.action, []);
+  
+  const middleware: UseFloatingOptions['middleware'] = [
+    offset(optionsWithDefaults.offset),
+    flip({
+      fallbackAxisSideDirection: 'end',
+      //fallbackStrategy: 'initialPlacement',
+      crossAxis: false, // Useful with `shift()`, see: https://floating-ui.com/docs/flip
+      ...(optionsWithDefaults.boundary ? { boundary: optionsWithDefaults.boundary } : {}),
+      ...optionsWithDefaults.floatingUiFlipOptions,
+    }),
+    shift({
+      limiter: limitShift({ offset: 10 }),
+      ...(optionsWithDefaults.boundary ? { boundary: optionsWithDefaults.boundary } : {}),
+    }),
+  ];
+  
+  if (action === 'hover') {
+    middleware.push(hide({
+      strategy: 'escaped',
+      ...(optionsWithDefaults.boundary ? { boundary: optionsWithDefaults.boundary } : {}),
+    }));
+  }
+  if (optionsWithDefaults.arrowRef) {
+    middleware.push(arrow({ element: optionsWithDefaults.arrowRef }));
+  }
+  
+  const [isOpen, setIsOpen] = React.useState(false);
+  
+  const { context, refs, placement, floatingStyles } = useFloating({
+    open: isOpen,
+    onOpenChange: setIsOpen,
+    placement: optionsWithDefaults.placement,
+    strategy: 'fixed', // Use `fixed` to contain within the viewport (as opposed to containing block with `absolute`)
+    whileElementsMounted(referenceEl, floatingEl, update) {
+      const cleanup = autoUpdate(referenceEl, floatingEl, update, {
+        animationFrame: optionsWithDefaults.enablePreciseTracking,
+      });
+      return cleanup;
+    },
+    ...optionsWithDefaults.floatingUiOptions,
+    middleware: [
+      ...middleware,
+      ...(optionsWithDefaults.floatingUiOptions.middleware ?? []),
+    ],
+  });
+  
+  // Note: for `role="tooltip", no `aria-haspop` is necessary on the anchor because it is not interactive:
+  // https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup
+  const role = useRole(context, { role: 'tooltip' });
+  
+  const interactions: Array<ElementProps> = [
+    role,
+  ];
+  
+  if (action === 'click') {
+    interactions.push(useClick(context, { toggle: true }));
+    interactions.push(useDismiss(context));
+  } else if (action === 'hover') {
+    interactions.push(useFocus(context));
+    const { delay: groupDelay } = useDelayGroup(context);
+    const delay = optionsWithDefaults.hasDelayGroup ? groupDelay : {
+      open: 500/*ms*/, // Fallback time to open after if the cursor never "rests"
+      close: 200/*ms*/, // Allows the user to move the cursor from anchor to tooltip without closing
+    };
+    interactions.push(useHover(context, {
+      restMs: 20/*ms*/, // User's cursor must be at rest before opening
+      delay,
+    }));
+  }
+  
+  const { getReferenceProps, getFloatingProps, getItemProps } = useInteractions([
+    ...interactions,
+    ...optionsWithDefaults.floatingUiInteractions(context),
+  ]);
+  
+  // Keep the tooltip mounted for a little while after close to allow exit animations to occur
+  const { isMounted } = useTransitionStatus(context, { duration: { open: 0, close: 500 } });
+  
+  // Sync the `isOpen` state with browser `popover` state
+  React.useEffect(() => {
+    const floatingElement = refs.floating.current;
+    if (!floatingElement) { return; }
+    
+    const isPopoverShown = floatingElement.matches(':popover-open');
+    if (isOpen && !isPopoverShown) {
+      floatingElement.showPopover();
+    } else if (!isOpen && isPopoverShown) {
+      floatingElement.hidePopover();
+    }
+  }, [isOpen, refs.floating]);
+  
+  return {
+    context,
+    isOpen,
+    setIsOpen,
+    isMounted,
+    refs,
+    placement,
+    floatingStyles,
+    getReferenceProps,
+    getFloatingProps,
+    getItemProps,
+  };
+};
+
+
+// Derived from:
+// https://github.com/floating-ui/floating-ui/blob/master/packages/react/src/components/FloatingArrow.tsx
+type PopoverArrowOptions = {
+  context: FloatingContext,
+  // Forces a static offset over dynamic positioning under a certain condition.
+  staticOffset?: string | number | null;
+};
+type PopoverArrowResult = null | {
+  side: Side,
+  arrowX: undefined | number | string,
+  arrowY: undefined | number | string,
+};
+export const usePopoverArrow = (options: PopoverArrowOptions): PopoverArrowResult => {
+  const {
+    context: {
+      placement,
+      elements: { floating },
+      middlewareData: { arrow },
+    },
+    staticOffset,
+  } = options;
+  
+  if (!floating) { return null; }
+  
+  const [tooltopSide, tooltipAlignment] = placement.split('-') as [Side, Alignment];
+  // const isVerticalSide = side === 'top' || side === 'bottom';
+  // 
+  // const isRTL = platform.isRTL(floating);
+  // const yOffsetProp = staticOffset && alignment === 'end' ? 'bottom' : 'top';
+  // let xOffsetProp = staticOffset && alignment === 'end' ? 'right' : 'left';
+  // if (staticOffset && isRTL) {
+  //   xOffsetProp = alignment === 'end' ? 'left' : 'right';
+  // }
+  
+  const invertSide = (side: Side) => {
+    switch (side) {
+      case 'top': return 'bottom';
+      case 'bottom': return 'top';
+      case 'left': return 'right';
+      case 'right': return 'left';
+      default: return side;
+    }
+  };
+  
+  return {
+    side: invertSide(tooltopSide),
+    arrowX: staticOffset || (typeof arrow?.x === 'number' ? `${arrow.x}px` : undefined),
+    arrowY: staticOffset || (typeof arrow?.y === 'number' ? `${arrow.y}px` : undefined),
+  };
+};

package/src/docs/Changelog.mdx

@@ -0,0 +1,7 @@
+
+import { Meta, Markdown } from '@storybook/blocks';
+import Changelog from '../../CHANGELOG.md?raw';
+
+<Meta title="Docs/Change log"/>
+
+<Markdown>{Changelog}</Markdown>

package/src/docs/Colors.mdx

@@ -0,0 +1,113 @@
+
+import cx from 'classnames/dedupe';
+import { Meta, Unstyled } from '@storybook/blocks';
+
+import colorContrast from 'postcss-color-contrast/js';
+import { colorsByCategory } from '../styling/variables.ts';
+
+import { H4, H5 } from '../typography/Heading/Heading.tsx';
+import { TooltipProvider } from '../components/overlays/Tooltip/TooltipProvider.tsx';
+import { Panel } from '../components/containers/Panel/Panel.tsx';
+
+import cl from './Colors.module.scss';
+
+
+<Meta title="Docs/Colors"/>
+
+# Colors
+
+## Usage
+
+All color tokens are available as static variables of the form `bk.$color-<token>`.
+
+```css
+.my-component {
+  color: bk.$color-neutral-500;
+}
+```
+
+## Primitive Color Tokens
+
+Primitive color tokens are the basic color definitions which are not dependent on any particular theme or semantics. Other color tokens may be defined in terms of these.
+
+<Unstyled>
+  <div className={cl['primitive-colors']}>
+    {Object.entries(colorsByCategory).map(([colorCategoryName, colorCategory]) =>
+      <section key={colorCategoryName} className={cl['color-category']}>
+        <H4>{colorCategoryName}</H4>
+        <dl className={cl['colors-list']}>
+          {Object.entries(colorCategory).map(([colorName, { weight, color }]) =>
+            <TooltipProvider key={colorName} tooltip={<code className="bk-body-text">{`bk.$color-${colorName}`}</code>}>
+              <div className={cl['color']} tabIndex="1"
+                style={{ '--color': color, '--contrast': colorContrast(color, ['#e5e5e5', '#171717']) }}
+              >
+                <dt>{weight}</dt>
+                <dd>{color}</dd>
+              </div>
+            </TooltipProvider>
+          )}
+        </dl>
+      </section>
+    )}
+  </div>
+</Unstyled>
+
+{/*
+## Spectrum (experiment)
+
+{/* https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl * /}
+[/* https://www.youtube.com/watch?v=gPacarD9NuA * /}
+<section className={cl['color-category']}>
+  <dl className={cx(cl['colors-list'], cl['color-spectrum'])} style={{ '--item-size': '4rem', gap: 0 }}>
+    {Array.from({ length: 10 }).map((_, i) =>
+      <div key={i} className={cl['color']} style={{ background: `oklab(calc(20% + ${i/9} * 60%) -50% 0)` }}>
+        <dt></dt>
+        <dd></dd>
+      </div>
+    )}
+  </dl>
+  <dl className={cx(cl['colors-list'], cl['color-spectrum'])} style={{ '--item-size': '4rem', gap: 0 }}>
+    {Array.from({ length: 10 }).map((_, i) =>
+      <div key={i} className={cl['color']} style={{ background: `oklab(calc(20% + ${i/9} * 60%) 0% -60%)` }}>
+        <dt></dt>
+        <dd></dd>
+      </div>
+    )}
+  </dl>
+    <dl className={cx(cl['colors-list'], cl['color-spectrum'])} style={{ '--item-size': '4rem', gap: 0 }}>
+    {Array.from({ length: 10 }).map((_, i) =>
+      <div key={i} className={cl['color']} style={{ background: `oklab(calc(20% + ${i/9} * 60%) 0% 0%)` }}>
+        <dt></dt>
+        <dd></dd>
+      </div>
+    )}
+  </dl>
+</section>
+*/}
+
+
+## Theming
+
+Baklava supports both light and dark themes. By default, the user's preferred color scheme is chosen.
+
+<Unstyled>
+  <div className={cl['theme-demo']}>
+    <Panel className="bk-theme--dark">
+      <Panel.Heading>
+        This is a panel in dark theme: <code className="bk-body-text">.bk-theme--dark</code>
+      </Panel.Heading>
+      
+      <Panel className="bk-theme--light">
+        <Panel.Heading>
+          This is a panel in light theme: <code className="bk-body-text">.bk-theme--light</code>
+        </Panel.Heading>
+        
+        {/* XXX this doesn't work without `@scope`, light wins over dark due to the order in which they were defined
+        <Panel className="bk-theme--invert">
+          <Panel.Heading>This panel inverts the theme of the parent.</Panel.Heading>
+        </Panel>
+        */}
+      </Panel>
+    </Panel>
+  </div>
+</Unstyled>

package/src/docs/Colors.module.scss

@@ -0,0 +1,56 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+@use '../styling/context/theming_mixins.scss' as theming;
+
+@layer storybook {
+  .primitive-colors {
+    display: flex;
+    flex-direction: column;
+    gap: 1lh;
+    
+    .color-category {
+      .colors-list {
+        --item-size: 5rem;
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(min(var(--item-size), 100%), 1fr));
+        gap: 2ch;
+        
+        .color {
+          min-height: 4rem;
+          padding: 0.5rem;
+          background: var(--color);
+          border: 1px solid color-mix(in sRGB, var(--color) 90%, black);
+          box-shadow: 1px 1px 3px color-mix(in sRGB, var(--color) 90%, black);
+          
+          display: flex;
+          flex-direction: column;
+          justify-content: end;
+          
+          color: black;
+          font-size: 0.8rem;
+          
+          dt, dd {
+            all: unset;
+            /* color: color-contrast(var(--color) vs black, white); // Insufficient browser support */
+            /* color: white; mix-blend-mode: difference; */
+            
+            color: var(--contrast);
+          }
+          dt {
+            font-weight: 600;
+          }
+        }
+        
+        &.color-spectrum .color {
+          background: color-mix(in sRGB, var(--color) calc(var(--lightness) / 9 * 100%), black);
+        }
+      }
+    }
+  }
+  
+  .theme-demo {
+    @include theming.theme-invert;
+  }
+}

package/src/docs/Iconography.mdx

@@ -0,0 +1,70 @@
+
+import cx from 'classnames/dedupe';
+import { Meta, Unstyled, IconGallery, IconItem } from '@storybook/blocks';
+
+import { TooltipProvider } from '../components/overlays/Tooltip/TooltipProvider.tsx';
+import { icons } from '../assets/icons/_icons.ts';
+import { Icon } from '../components/graphics/Icon/Icon.tsx';
+
+import cl from './Iconography.module.scss';
+
+
+<Meta title="Docs/Iconography"/>
+
+# Iconography
+
+Baklava comes with an icon pack using SVG sprite images. The `Icon` component is used to render a given icon by name:
+
+```tsx
+<Icon icon="assessment"/>
+```
+
+This will render:
+
+<Icon icon="assessment" style={{ fontSize: '2rem' }}/>
+
+Icons by default will adapt to the current text styling. To resize an icon, change the `font-size` in CSS. Similarly, you can change the CSS `color` property to update the icon's color.
+
+
+## Overview
+
+<IconGallery>
+  {Object.keys(icons).map(iconName =>
+    <IconItem key={iconName} name={iconName}>
+      <Icon icon={iconName} className="icon"/>
+    </IconItem>
+  )}
+</IconGallery>
+
+{/*
+<Unstyled>
+  <ul className={cl['icons-overview']}>
+    {Object.entries(icons).map(([iconName, iconDef]) =>
+      <TooltipProvider key={iconName} tooltip={iconName}>
+        <li><Icon icon={iconName} className="icon"/></li>
+      </TooltipProvider>
+    )}
+  </ul>
+</Unstyled>
+*/}
+
+## Details
+
+<table className={cl['icons-table']}>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Icon</th>
+      <th>Code</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(icons).map(([iconName, iconDef]) =>
+      <tr key={iconName}>
+        <td className={cx(cl['cell'], cl['cell-name'])}>{iconName}</td>
+        <td className={cx(cl['cell'], cl['cell-icon'])}><Icon icon={iconName}/></td>
+        <td className={cx(cl['cell'], cl['cell-code'])}><code>{`<Icon icon=${JSON.stringify(iconName)}/>`}</code></td>
+      </tr>
+    )}
+  </tbody>
+</table>

package/src/docs/Iconography.module.scss

@@ -0,0 +1,37 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+@layer storybook {
+  .icons-overview {
+    max-width: 40rem;
+    margin-block: 1.2rem;
+    
+    display: flex;
+    flex-flow: row wrap;
+    gap: 0.8rem;
+    
+    :global(.icon) {
+      font-size: 1.8em;
+      
+      outline: 1px solid transparent;
+      @media (prefers-reduced-motion: no-preference) {
+        transition: outline-color 200ms ease-in-out;
+      }
+    }
+    
+    &:hover {
+      :global(.icon) {
+        outline-color: color-mix(in sRGB, currentColor 10%, transparent);
+      }
+    }
+  }
+  
+  .icons-table {
+    //.cell {}
+    
+    .cell-icon {
+      font-size: 1.4em;
+    }
+  }
+}

package/src/docs/Introduction.mdx

@@ -0,0 +1,26 @@
+
+import { Meta, Markdown } from '@storybook/blocks';
+
+<Meta title="Docs/Introduction"/>
+
+# Baklava,<br/>The Fortanix Design System
+
+Baklava is the design system created by [Fortanix](https://fortanix.com) to build user interfaces. It provides the design guidelines and components to ensure a consistent user experience across our products and marketing material.
+
+
+## Usage
+
+1. Clone Baklava
+```
+git clone https://github.com/fortanix/baklava
+```
+
+2. Install dependencies
+```
+npm run install-project
+```
+
+3. Run Baklava
+```
+npm start
+```

package/src/docs/Typography.mdx

@@ -0,0 +1,109 @@
+
+import { Meta, Unstyled } from '@storybook/blocks';
+import { linkTo } from '@storybook/addon-links';
+
+import { fontSizes } from '../styling/variables.ts';
+
+import * as Heading from '../typography/Heading/Heading.tsx';
+import { ButtonAsLink } from '../components/actions/ButtonAsLink/ButtonAsLink.tsx';
+
+import cl from './Typography.module.scss';
+
+<Meta title="Docs/Typography"/>
+
+
+# Typography
+
+## Font families
+
+<div className={cl['font-family-list']}>
+  <table>
+    <thead>
+      <tr>
+        <th>Font: <code>body</code></th>
+      </tr>
+    </thead>
+    <tbody>
+      {[400, 600,700].map(weight =>
+        <tr key={weight} style={{ fontFamily: 'Open Sans', fontWeight: weight, fontSize: fontSizes.m }}>
+          <td>Open Sans {weight}</td>
+        </tr>
+      )}
+    </tbody>
+  </table>
+  
+  <table>
+    <thead>
+      <tr>
+        <th>Font: <code>display</code></th>
+      </tr>
+    </thead>
+    <tbody>
+      {[100, 200, 300, 400, 500, 600, 700].map(weight =>
+        <tr key={weight} style={{ fontFamily: 'Montserrat', fontWeight: weight, fontSize: fontSizes.m }}>
+          <td>Montserrat {weight}</td>
+        </tr>
+      )}
+    </tbody>
+  </table>
+  <table>
+    <thead>
+      <tr>
+        <th>Font: <code>code</code></th>
+      </tr>
+    </thead>
+    <tbody>
+      {[400].map(weight =>
+        <tr key={weight} style={{ fontFamily: 'Source Code Pro', fontWeight: weight, fontSize: fontSizes.m }}>
+          <td>Source Code Pro {weight}</td>
+        </tr>
+      )}
+    </tbody>
+  </table>
+</div>
+
+
+## Font sizes
+
+Font sizes are defined in units of `rem`. The exact pixel value of `rem` varies, the table below lists an approximation
+based on 1rem = 16px. Baklava sets a dynamic font size such that the actual font size changes slightly depending on the
+width of the viewport: on smaller devices (e.g. mobile), font sizes will be smaller.
+
+<div className={cl['font-size-list']}>
+  <table>
+    <thead>
+      <tr>
+        <th>Font size</th>
+        <th>Example text</th>
+        <th>rem</th>
+        <th>px (approximate)</th>
+      </tr>
+    </thead>
+    <tbody>
+      {Object.entries(fontSizes).map(([fontSizeName, fontSize]) =>
+        <tr key={fontSizeName}>
+          <td><code>bk.${fontSizeName}</code></td>
+          <td style={{ fontSize: `${fontSize.sizeInRem}rem` }}>This text has font size {fontSize.sizeQualifier}</td>
+          <td>{fontSize.sizeInRem}rem</td>
+          <td>~{(fontSize.sizeInRem * 16).toFixed(2)}px</td>
+        </tr>
+      )}
+    </tbody>
+  </table>
+</div>
+
+
+## Headings
+
+<Unstyled>
+  <Heading.H1>Heading 1</Heading.H1>
+  <Heading.H2>Heading 2</Heading.H2>
+  <Heading.H3>Heading 3</Heading.H3>
+  <Heading.H4>Heading 4</Heading.H4>
+  <Heading.H5>Heading 5</Heading.H5>
+  <Heading.H6>Heading 6</Heading.H6>
+</Unstyled>
+
+## See also
+
+- <ButtonAsLink onClick={linkTo(`typography/BodyText`)}>Body text</ButtonAsLink>

package/src/docs/Typography.module.scss

@@ -0,0 +1,22 @@
+/* Copyright (c) Fortanix, Inc.
+|* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
+|* the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+@layer storybook {
+  .font-family-list {
+    display: flex;
+    flex-flow: row wrap;
+    gap: 1rem;
+    align-items: start;
+    
+    > * {
+      min-width: fit-content;
+    }
+  }
+  
+  .font-size-list {
+    tr {
+      line-height: 1.6; /* Override Storybook's fixed line-height */
+    }
+  }
+}