@stack-spot/citric-react 0.1.0

package/src/overlay.ts

@@ -0,0 +1,276 @@
+import { createRoot } from 'react-dom/client'
+import { WithDataAttributes } from './types'
+import { styleObjectToCssString } from './utils/css'
+
+export type RelativePosition = 'top' | 'bottom' | 'left' | 'right'
+
+export interface OverlayOptions<T extends keyof React.JSX.IntrinsicElements> {
+  /**
+   * The tag to render when creating the overlay element.
+   * 
+   * @default 'div'
+   */
+  tag?: T,
+  /**
+   * The content of the overlay element.
+   * 
+   * When this is a string, a number or a boolean, the content will be appended to the overlay element. Otherwise, a new React concurrent
+   * instance will be creted to render the React tree node inside the overlay element.
+   */
+  content: React.ReactNode,
+  /**
+   * Which element will be used as a reference to position the overlay element.
+   * This can be either an HTMLElement or an event. If this is a event, the element in `event.target` will be used unless `reference` is
+   * set to `'mouse'`, in this case, the reference will be the current cursor position.
+   */
+  target: Event | HTMLElement,
+  /**
+   * Takes effect when `target` is a MouseEvent. If this is set to `'mouse'`, then the position to be used as a reference to place the
+   * overlay will be the current cursor position.
+   * 
+   * @default 'element'
+   */
+  reference?: 'element' | 'mouse',
+  /**
+   * Where, relative to `target`, should we place the overlay?
+   * 
+   * @default 'top'
+   */
+  position?: RelativePosition,
+  /**
+   * TODO: implement this.
+   * 
+   * Affects the positioning of the overlay relative to `target`. While `position` defines the overlay position in the main axis,
+   * `alignment` defines the position in the cross axis.
+   * 
+   * @default 'center'
+   */
+  alignment?: 'start' | 'center' | 'end',
+  /**
+   * TODO: implement this (currently, only 'fade' works).
+   * 
+   * - fade: the overlay fades in to appear and fades out to disappear.
+   * - accordion: the element grows to appear and shrinks to disappear. The direction of the growth depends on `position`.
+   * - bubble: grows from scale(0) to scale(1) from its center to appear. Shrinks from scale(1) to scale(0) to disappear.
+   * - none: no animation is used.
+   * 
+   * @default 'fade'
+   */
+  animation?: 'fade' | 'accordion' | 'bubble' | 'none',
+  /**
+   * The attributes for the HTMLElement that will be created for the overlay.
+   */
+  attributes?: JSX.IntrinsicElements[T] & WithDataAttributes & { inert?: boolean },
+}
+
+interface Position {
+  top: number,
+  left: number,
+}
+
+interface PositionWithRelativeData extends Position {
+  relativeTo: RelativePosition,
+}
+
+type CalculatePosOptions = Pick<Required<OverlayOptions<any>>, 'position' | 'target' | 'reference'>
+  & { overlay: HTMLElement }
+
+const animationDurationMS = 300
+
+function hasMargins(element: HTMLElement) {
+  const s = element.style
+  return s.margin || s.marginTop || s.marginBottom || s.marginLeft || s.marginRight
+}
+
+function calculatePosition({
+  overlay,
+  reference,
+  target,
+  position: relativePosition,
+}: CalculatePosOptions): Position & { overlayWidth: number, overlayHeight: number } {
+  const overlayDimensions = overlay.getBoundingClientRect()
+  if (hasMargins(overlay)) {
+    const style = overlay.computedStyleMap()
+    const mt = parseInt(style.get('margin-top')?.toString() ?? '0')
+    const mb = parseInt(style.get('margin-bottom')?.toString() ?? '0')
+    const ml = parseInt(style.get('margin-left')?.toString() ?? '0')
+    const mr = parseInt(style.get('margin-right')?.toString() ?? '0')
+    if (mt) overlayDimensions.height += mt
+    if (mb) overlayDimensions.height += mb
+    if (ml) overlayDimensions.width += ml
+    if (mr) overlayDimensions.width += mr
+  }
+  const referencePosition = { top: 0, left: 0, overlayWidth: overlayDimensions.width, overlayHeight: overlayDimensions.height }
+  if (reference === 'mouse' && target instanceof MouseEvent) {
+    referencePosition.top = target.clientY
+    referencePosition.left = target.clientX
+  } else {
+    const element = target instanceof Event ? target.target : target
+    if (!(element instanceof HTMLElement)) return referencePosition
+    const elementDimensions = element.getBoundingClientRect()
+    switch (relativePosition) {
+      case 'top':
+        referencePosition.top = elementDimensions.top + window.scrollY
+        referencePosition.left = elementDimensions.left + elementDimensions.width / 2 + window.scrollX
+        break
+      case 'bottom':
+        referencePosition.top = elementDimensions.bottom + window.scrollY
+        referencePosition.left = elementDimensions.left + elementDimensions.width / 2 + window.scrollX
+        break
+      case 'left':
+        referencePosition.top = elementDimensions.top + elementDimensions.height / 2 + window.scrollY
+        referencePosition.left = elementDimensions.left + window.scrollX
+        break
+      case 'right':
+        referencePosition.top = elementDimensions.top + elementDimensions.height / 2 + window.scrollY
+        referencePosition.left = elementDimensions.right + window.scrollX
+    }
+  }
+  const position = { ...referencePosition }
+  switch (relativePosition) {
+    case 'top':
+      position.top -= overlayDimensions.height
+      position.left -= overlayDimensions.width / 2
+      break
+    case 'bottom':
+      position.left -= overlayDimensions.width / 2
+      break
+    case 'left':
+      position.top -= overlayDimensions.height / 2
+      position.left -= overlayDimensions.width
+      break
+    case 'right':
+      position.top -= overlayDimensions.height / 2
+  }
+  return position
+}
+
+function getSafeOverlayPosition(
+  options: Omit<CalculatePosOptions, 'position'>, positionPriority: RelativePosition[], fallback?: PositionWithRelativeData,
+): PositionWithRelativeData {
+  if (!positionPriority.length) return fallback ?? { top: 0, left: 0, relativeTo: 'top' }
+  const [relativePosition, ...remainingRelativePositions] = positionPriority
+  const position = { ...calculatePosition({ ...options, position: relativePosition }), relativeTo: relativePosition }
+  switch (relativePosition) {
+    case 'top':
+      if (position.left < 0) position.left = 0
+      if (position.left + position.overlayWidth > document.body.clientWidth) {
+        position.left = document.body.clientWidth - position.overlayWidth
+      }
+      if (position.top < 0) return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      break
+    case 'bottom':
+      if (position.left < 0) position.left = 0
+      if (position.left + position.overlayWidth > document.body.clientWidth) {
+        position.left = document.body.clientWidth - position.overlayWidth
+      }
+      if (position.top + position.overlayHeight > document.body.clientHeight) {
+        return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      }
+      break
+    case 'left':
+      if (position.top < 0) position.top = 0
+      if (position.top + position.overlayHeight > document.body.clientHeight) {
+        position.top = document.body.clientHeight - position.overlayHeight
+      }
+      if (position.left < 0) return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      break
+    case 'right':
+      if (position.top < 0) position.top = 0
+      if (position.top + position.overlayHeight > document.body.clientHeight) {
+        position.top = document.body.clientHeight - position.overlayHeight
+      }
+      if (position.left + position.overlayWidth > document.body.clientWidth) {
+        return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      }
+  }
+  return position
+}
+
+function invert(position: RelativePosition): RelativePosition {
+  switch (position) {
+    case 'bottom': return 'top'
+    case 'top': return 'bottom'
+    case 'left': return 'right'
+    case 'right': return 'left'
+  }
+}
+
+function oppositeAxis(position: RelativePosition): [RelativePosition, RelativePosition] {
+  return (position === 'top' || position === 'bottom') ? ['left', 'right'] : ['top', 'bottom']
+}
+
+function reactAttributeToHTML(attribute: string) {
+  return attribute === 'className' ? 'class' : attribute
+}
+
+function setElementAttributes(element: HTMLElement, attributes: Record<string, any> | undefined, ignore: string[] = []) {
+  for (const attr in attributes) {
+    if (attributes[attr] !== undefined && !ignore.includes(attr)) element.setAttribute(reactAttributeToHTML(attr), attributes[attr])
+  }
+}
+
+/**
+ * Appends a new HTML Element to the tag "body". This element is absolutely positioned and its position is calculated according to the
+ * options passed as parameter.
+ * 
+ * This function returns both the newly created HTML Element and a function to remove it.
+ * @param options {@link OverlayOptions}.
+ * @returns an object with two keys: "overlay" (the HTML Element created) and "hide" (a function to remove the element from the document).
+ */
+export function showOverlay<T extends keyof React.JSX.IntrinsicElements = 'div'>(
+  { tag, content, target, reference = 'element', position = 'top', attributes }: OverlayOptions<T>,
+) {
+  const overlay = document.createElement(tag || 'div')
+  overlay.style = `z-index: 9999; pointer-events: none; position: absolute; opacity: 0; transition: opacity ${animationDurationMS / 1000}s; ${styleObjectToCssString(attributes?.style)}`
+  overlay.inert = true
+  setElementAttributes(overlay, attributes, ['style', 'inert'])
+  document.body.append(overlay)
+  let unmount: (() => void) | undefined
+  if (['string', 'number', 'boolean'].includes(typeof content)) {
+    overlay.append(`${content}`)
+    unmount = () => document.body.removeChild(overlay)
+  } else {
+    const root = createRoot(overlay)
+    root.render(content)
+    unmount = () => {
+      root.unmount()
+      document.body.removeChild(overlay)
+    }
+  }
+  setTimeout(() => {
+    const overlayPos = getSafeOverlayPosition(
+      { overlay, reference, target },
+      [position, invert(position), ...oppositeAxis(position)],
+    )
+    overlay.style = `z-index: 9999; position: absolute; opacity: 1; transition: opacity ${animationDurationMS / 1000}s; top: ${overlayPos.top}px; left: ${overlayPos.left}px; ${styleObjectToCssString(attributes?.style)}`
+    if (attributes && 'inert' in attributes && attributes.inert) overlay.style.pointerEvents = 'none'
+    else overlay.inert = false
+    overlay.classList.add(overlayPos.relativeTo)
+  }, 0)
+  
+  return {
+    /**
+     * The overlay element created.
+     */
+    overlay,
+    /**
+     * Removes the overlay element.
+     * @returns a promise that completes when the element is fully removed (after any animation).
+     */
+    hide: () => new Promise<void>((resolve) => {
+      overlay.style.opacity = '0'
+      overlay.style.pointerEvents = 'none'
+      overlay.inert = true
+      setTimeout(() => {
+        try {
+          unmount()
+        } catch { /* empty */ }
+        resolve()
+      }, animationDurationMS)
+    }),
+    ready: new Promise<void>((resolve) => {
+      setTimeout(resolve, animationDurationMS)
+    }),
+  }
+}

package/src/types.ts

@@ -0,0 +1,226 @@
+import { ColorKey, ColorPaletteName, ColorSchemeName } from '@stack-spot/portal-theme'
+import { RadiusKey, SpacingKey } from '@stack-spot/portal-theme/dist/definition'
+
+export interface WithColorScheme {
+  colorScheme?: ColorSchemeName,
+}
+
+export interface WithColorPalette {
+  colorPalette?: ColorPaletteName,
+}
+
+export interface WithColor {
+  color?: ColorKey,
+}
+
+export type WithDataAttributes = { [key: `data-${string}`]: string | undefined }
+
+export type TextAppearance = 'body1' | 'body2' | 'code1' | 'code2' | 'display1' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'microtext1' |
+  'overheader1' | 'overheader2' | 'subtitle1' | 'subtitle2' | 'subtitle3' | 'subtitle4'
+
+// increase this list as needed. Generic uses of `JSX.IntrinsicElements` may lead to expensive operations.
+// export interface HTMLTag {
+//   a: HTMLAnchorElement,
+//   blockquote: HTMLQuoteElement,
+//   button: HTMLButtonElement,
+//   div: HTMLDivElement,
+//   form: HTMLFormElement,
+//   h1: HTMLHeadingElement,
+//   h2: HTMLHeadingElement,
+//   h3: HTMLHeadingElement,
+//   h4: HTMLHeadingElement,
+//   h5: HTMLHeadingElement,
+//   h6: HTMLHeadingElement,
+//   hr: HTMLHeadingElement,
+//   i: HTMLElement,
+//   image: HTMLImageElement,
+//   input: HTMLInputElement,
+//   label: HTMLLabelElement,
+//   li: HTMLLIElement,
+//   nav: HTMLElement,
+//   p: HTMLParagraphElement,
+//   pre: HTMLPreElement,
+//   select: HTMLSelectElement,
+//   small: HTMLElement,
+//   span: HTMLSpanElement,
+//   table: HTMLTableElement,
+//   td: HTMLTableCellElement,
+//   th: HTMLTableCellElement,
+//   tr: HTMLTableRowElement,
+//   textarea: HTMLTextAreaElement,
+//   ul: HTMLUListElement,
+// }
+
+// export type HTMLExtension<K extends keyof HTMLTag, Props, Omitted extends string = ''> = 
+//   (Omitted extends ''
+//     ? React.DetailedHTMLProps<React.HTMLAttributes<HTMLTag[K]>, HTMLTag[K]>
+//     : Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLTag[K]>, HTMLTag[K]>, Omitted>
+//   ) & Props
+
+
+
+export type HTMLExtension<K extends keyof React.JSX.IntrinsicElements, Props, Omitted extends string = ''> = 
+  (Omitted extends ''
+    ? React.JSX.IntrinsicElements[K]
+    : Omit<React.JSX.IntrinsicElements[K], Omitted>
+  ) & Props
+
+export interface WithStyleShortcuts {
+  /**
+   * Sets a theme color for the background.
+   */
+  bg?: ColorKey,
+  /**
+   * Sets a theme color for the foreground.
+   */
+  fg?: ColorKey,
+  /**
+   * Sets a theme color for the border and set it to 1px width.
+   */
+  border?: ColorKey,
+  /**
+   * Sets the border radius.
+   */
+  radius?: RadiusKey,
+  /**
+   * Sets the margin for every side.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a list of numbers is provided, the theme
+   * variable is used for each of the positions, following the CSS order ([top, right, bottom, left]) When a string is provided, this acts
+   * as a shortcut for `style.margin`.
+   */
+  m?: SpacingKey | SpacingKey[] | string,
+  /**
+   * Sets the margin from the top.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.marginTop`.
+   */
+  mt?: SpacingKey | string,
+  /**
+   * Sets the margin from the bottom.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.marginBottom`.
+   */
+  mb?: SpacingKey | string,
+  /**
+   * Sets the margin from the left.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.marginLeft`.
+   */
+  ml?: SpacingKey | string,
+  /**
+   * Sets the margin from the right.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.marginRight`.
+   */
+  mr?: SpacingKey | string,
+  /**
+   * Sets the padding for every side.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a list of numbers is provided, the theme
+   * variable is used for each of the positions, following the CSS order ([top, right, bottom, left]) When a string is provided, this acts
+   * as a shortcut for `style.padding`.
+   */
+  p?: SpacingKey | SpacingKey[] | string,
+  /**
+   * Sets the padding from the top.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.paddingTop`.
+   */
+  pt?: SpacingKey | string,
+  /**
+   * Sets the padding from the bottom.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.paddingBottom`.
+   */
+  pb?: SpacingKey | string,
+  /**
+   * Sets the padding from the left.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.paddingLeft`.
+   */
+  pl?: SpacingKey | string,
+  /**
+   * Sets the padding from the right.
+   * 
+   * When a number is provided, the theme variable is used "spacing-1, ..., spacing-19". When a string is provided, this acts as a shortcut
+   * for `style.paddingRight`.
+   */
+  pr?: SpacingKey | string,
+  /**
+   * Shortcut for `style.width`.
+   */
+  w?: string | number,
+  /**
+   * Shortcut for `style.height`.
+   */
+  h?: string | number,
+  /**
+   * Shortcut for `style.flex`.
+   */
+  flex?: React.CSSProperties['flex'],
+  /**
+   * Shortcut for `style.justifyContent`.
+   */
+  justifyContent?: React.CSSProperties['justifyContent'],
+  /**
+   * Shortcut for `style.alignItems`.
+   */
+  alignItems?: React.CSSProperties['alignItems'],
+  /**
+   * Shortcut for `style.gap`.
+   */
+  gap?: React.CSSProperties['gap'],
+}
+
+export interface CitricController {
+  /**
+   * If set, instead of rendering the HTML tag "a", the Link component will render the return value of this function.
+   * @param props the props for the anchor element
+   * @returns 
+   */
+  renderLink?: (props: JSX.IntrinsicElements['a']) => React.ReactElement,
+  /**
+   * A function to run whenever the component Button is clicked.
+   * @param event the click event.
+   * @param analytics true if analytics are enabled for this button, false otherwise.
+   */
+  onClickButton?: (event: React.MouseEvent<HTMLButtonElement>, analytics: boolean) => void,
+  /**
+   * A function to run whenever the component Link is clicked.
+   * @param event the click event.
+   * @param analytics true if analytics are enabled for this link, false otherwise.
+   */
+  onClickLink?: (event: React.MouseEvent<HTMLAnchorElement>, analytics: boolean) => void,
+  /**
+   * A custom renderer for error feedbacks.
+   * 
+   * By default, a simple text with the error message is rendered.
+   * 
+   * Errors are rendered when they're caught in an ErrorBoundary or AsyncContent.
+   * @param error the error caught.
+   * @returns the UI for the feedback.
+   */
+  renderError?: (error: any) => React.ReactElement,
+  /**
+   * A custom renderer for loading feedbacks.
+   * 
+   * By default, the component "ProgressCircular" is rendered with some padding.
+   * 
+   * Loadings are rendered in Suspended calls or in AsyncContent.
+   * @returns the UI for the feedback.
+   */
+  renderLoading?: () => void,
+  /**
+   * Function to run whenever an Error is caught.
+   * @param error the error caught.
+   */
+  onError?: (error: any) => void,
+}

package/src/utils/ValueController.ts

@@ -0,0 +1,28 @@
+import { pull } from 'lodash'
+
+export type ValueListener<T> = (value: T) => void
+
+export class ValueController<T> {
+  protected value: T
+  private listeners: ValueListener<T>[] = []
+  
+  constructor(value: T) {
+    this.value = value
+  }
+
+  onChange(listener: ValueListener<T>) {
+    this.listeners.push(listener)
+    return () => {
+      pull(this.listeners, listener)
+    }
+  }
+
+  setValue(value: T) {
+    this.value = value
+    this.listeners.forEach(l => l(value))
+  }
+
+  getValue() {
+    return this.value
+  }
+}

package/src/utils/acessibility.ts

@@ -0,0 +1,92 @@
+export type TagPriority = 'a' | 'button' | 'input' | 'textarea' | 'select' | 'other'
+export type TagPriorityElement = TagPriority | TagPriority[]
+
+interface FocusOptions {
+  /**
+   * Instead of focusing the first element overall, focus the first according to this list of priorities.
+   * 
+   * 'other' means elements that are normally not focusable, but have positive tabIndex values.
+   */
+  priority?: TagPriorityElement[],
+  /**
+   * Ignores any element that matches this query selector.
+   */
+  ignore?: string,
+}
+
+const selectors: Record<TagPriority, string> = {
+  a: 'a[href]:not(:disabled)',
+  button: 'button:not(:disabled)',
+  input: 'input:not(:disabled):not([type="hidden"])',
+  select: 'textarea:not(:disabled)',
+  textarea: 'select:not(:disabled)',
+  other: '[tabindex]:not([tabindex="-1"])',
+}
+
+/**
+ * Focus the first focusable child of the element provided. If the element has no focusable child, nothing happens.
+ * 
+ * A priority list can be passed in the second parameter, as an option. If it's provided, it will focus the first element according to the
+ * list.
+ * 
+ * An ignore query selector can also be passed in the options parameter. If the first focusable element matches the query selector, the
+ * next element is focused instead.
+ * 
+ * Elements with `auto-focus={false}` will be ignored.
+ * 
+ * @example
+ * Suppose the children of element are: h1, button, p, input, select.
+ * 1. We don't pass a priority list. The focused element will be the button.
+ * 2. Our priority list is ['button']. The focused element will be the button.
+ * 3. Our priority list is ['input', 'button']. The focused element will be the input.
+ * 4. Our priority list is ['select', 'input']. The focused element will be the select.
+ * 5. Our priority list is [['select', 'input'], 'button']. The focused element will be the input.
+ * 
+ * @param element the element to search a child to focus.
+ * @param options optional.
+ */
+export function focusFirstChild(element: HTMLElement | Document | null | undefined, { priority = [], ignore }: FocusOptions = {}) {
+  const allFocusableTags: TagPriority[] = ['a', 'button', 'input', 'other', 'select', 'textarea']
+  const focusableList: (NodeListOf<HTMLElement> | undefined)[] = [
+    element?.querySelectorAll(allFocusableTags.map(t => selectors[t]).join(', ')),
+  ]
+  for (const p of priority) {
+    const tags = Array.isArray(p) ? p : [p]
+    const querySelectors = tags.map(t => selectors[t])
+    focusableList.unshift(element?.querySelectorAll(querySelectors.join(', ')))
+  }
+  for (const focusable of focusableList ?? []) {
+    for (const f of focusable ?? []) {
+      if (f.getAttribute('auto-focus') !== 'false' && (!ignore || !f.matches(ignore))) {
+        const styles = window.getComputedStyle(f)
+        if (styles.display != 'none' && styles.visibility != 'hidden') return f.focus()
+      }
+    }
+  }
+}
+
+/**
+ * Checks if an element can receive focus.
+ * 
+ * Elements can receive focus only if:
+ * - they exist;
+ * - they're visible;
+ * - they're not disabled;
+ * - they are a focusable tag name or have a positive tab index;
+ * - they don't have a negative tab index.
+ * @param element the element to check.
+ * @returns true if the element is focusable, false otherwise.
+ */
+export function isFocusable(element?: Element | null) {
+  if (!element) return false
+  // is disabled: return false
+  if (element.ariaDisabled || element.getAttribute('disabled') !== null) return false
+  // is invisible: return false
+  if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) return false
+  // has tab index: return false if negative, true otherwise
+  const tabIndexStr = element.getAttribute('tabindex')
+  const tabIndex = tabIndexStr ? parseInt(tabIndexStr) : undefined
+  if (tabIndex !== undefined) return tabIndex >= 0
+  // check the tag name
+  return ['a', 'button', 'input', 'iframe', 'select', 'textarea'].includes(element.tagName.toLowerCase() ?? '')
+}