Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
10.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file layerSlideRules.ts
 * @input A layer's placement and alignment
 * @output The `@position-try` rules for its slide options and their names, and
 *   the beside and fit options of a layer that must never settle over its
 *   anchor
 * @position Layer runtime geometry; the slide of spec:AST-059 FR4
 *
 * The slide is a position option whose area spans the whole alignment axis,
 * so a layer wider than the room beside its trigger on both sides still
 * reaches the side of the trigger that has room on the placement axis. A
 * plain `<position-area>` fallback would keep the base margins and insets,
 * which belong to an edge-aligned layer: the alignment-axis gutter on one
 * edge only, and the clearance/gutter pair of the base side on the placement
 * axis. Each slide option therefore carries its own declarations — the
 * gutter on both alignment-axis edges, and the clearance facing the anchor
 * with the gutter on the far edge of the side it lands on.
 *
 * An above or below layer that must never settle over its anchor
 * (spec:AST-059 FR4, Tooltip) uses one combined fallback list from the start,
 * and no option in it overlaps the anchor. `beside` lands on a
 * side across the alignment axis, spanning the whole block axis, at the
 * content's own inline size, so it fits only where the layer fits without
 * squeezing. `fit` lands above or below sized to the room on that side, so
 * overflow scrolls inside the layer, and is never smaller than half of the room
 * the trigger leaves on the block axis, so it fits only on the side with more
 * room; the list tries both only after the layer's own position, the opposite
 * side at the layer's own size and `beside`, so only content taller than the
 * room on both sides is sized to a room. No option is sized to whatever room
 * is left: a browser keeps a layer on the option it last used for as long as
 * that option still fits, so such an option would hold an open layer on a side
 * shrunk to a sliver after its anchor moved. Chromium applies a position
 * option's width and height properties but not their min/max forms, so the
 * sizes are `inline-size` and `block-size`. Inside a scrolling panel, Chromium
 * does not choose an option again while the panel scrolls, and it shifts a box
 * that runs out of room back into the room, onto the anchor. So the layer and
 * every option align `unsafe` toward the anchor on the placement axis: a box
 * that runs out of room overflows away from the anchor instead.
 *
 * The rules are static — the anchor clearance travels through a custom
 * property — so one style sheet per document carries all of them. It is
 * installed from a layout effect, before the layer's first paint, rather than
 * through StyleX, whose `positionTry()` output is malformed in the pinned
 * release. The sheet lives in the document head, not beside or inside the
 * layer: a sibling would change what a parent's last child is, and text
 * inside a role-bearing layer would name it to assistive technology.
 */

import type {LayerAlignment, LayerPlacement} from './useLayer';
import {layerViewportInset} from './layerViewportInset.stylex';

/** The custom property a layer writes its anchor clearance to. */
export const LAYER_CLEARANCE_PROPERTY = '--_astryx-layer-clearance';

type Side = 'same' | 'opposite';

export function slideRuleName(
  placement: LayerPlacement,
  alignment: LayerAlignment,
  side: Side,
): string {
  return `--astryx-layer-slide-${placement}-${alignment}-${side}`;
}

const CLEARANCE = `var(${LAYER_CLEARANCE_PROPERTY}, 0px)`;

/** Two declarations: the `env()`-less fallback first, then the full value. */
function pair(property: string, fallback: string, value: string): string {
  return `${property}:${fallback};${property}:${value};`;
}

function blockGutter(property: string): string {
  return pair(
    property,
    layerViewportInset.gutterBlockFallback,
    layerViewportInset.gutterBlock,
  );
}

function inlineGutter(property: string): string {
  return pair(
    property,
    layerViewportInset.gutterInlineFallback,
    layerViewportInset.gutterInline,
  );
}

const OPPOSITE: Record<LayerPlacement, LayerPlacement> = {
  above: 'below',
  below: 'above',
  start: 'end',
  end: 'start',
};

function areaFor(placement: LayerPlacement): string {
  switch (placement) {
    case 'above':
      return 'self-block-start span-all';
    case 'below':
      return 'self-block-end span-all';
    case 'start':
      return 'self-inline-start span-all';
    case 'end':
      return 'self-inline-end span-all';
  }
}

/** The placement-axis margins for a layer resting on `placement`'s side. */
function placementMargins(placement: LayerPlacement): string {
  switch (placement) {
    case 'above':
      return `margin-block-end:${CLEARANCE};${blockGutter('margin-block-start')}`;
    case 'below':
      return `margin-block-start:${CLEARANCE};${blockGutter('margin-block-end')}`;
    case 'start':
      return `margin-inline-end:${CLEARANCE};${inlineGutter('margin-inline-start')}`;
    case 'end':
      return `margin-inline-start:${CLEARANCE};${inlineGutter('margin-inline-end')}`;
  }
}

/** The alignment-axis gutter on both edges, with the base inset reset. */
function alignmentMargins(placement: LayerPlacement): string {
  return placement === 'above' || placement === 'below'
    ? `${inlineGutter('margin-inline-start')}${inlineGutter('margin-inline-end')}inset-inline-start:0;inset-inline-end:0;`
    : `${blockGutter('margin-block-start')}${blockGutter('margin-block-end')}inset-block-start:0;inset-block-end:0;`;
}

function rule(
  placement: LayerPlacement,
  alignment: LayerAlignment,
  side: Side,
): string {
  const landing = side === 'same' ? placement : OPPOSITE[placement];
  return `@position-try ${slideRuleName(placement, alignment, side)}{position-area:${areaFor(landing)};${placementMargins(landing)}${alignmentMargins(landing)}}`;
}

const PLACEMENTS: ReadonlyArray<LayerPlacement> = [
  'above',
  'below',
  'start',
  'end',
];
const ALIGNMENTS: ReadonlyArray<LayerAlignment> = ['start', 'center', 'end'];

/**
 * The placement-axis alignment of a layer that keeps its anchor clear, on
 * `side` of its anchor: `unsafe`, toward the anchor, so a box that runs out of
 * room overflows away from the anchor rather than being shifted onto it.
 * `flip-block` swaps it with the side.
 */
export function anchorClearAlignment(side: LayerPlacement): string {
  return side === 'above' || side === 'start'
    ? 'unsafe self-end'
    : 'unsafe self-start';
}

/** The name of the `beside` option that lands on `side`, across the block axis. */
export function besideRuleName(side: 'start' | 'end'): string {
  return `--astryx-layer-beside-${side}`;
}

/**
 * The name of the `fit` option that lands on `side` sized to the room there,
 * which fits only while that side holds at least half of the room the trigger
 * leaves on the block axis.
 */
export function fitRuleName(side: 'above' | 'below'): string {
  return `--astryx-layer-fit-${side}`;
}

/**
 * `beside`: the slide's geometry on an inline side, at the content's own
 * inline size. A content-sized layer would otherwise wrap to whatever sliver
 * of room the trigger leaves and always fit. On the block axis it drops the
 * layer's own alignment toward its anchor, so it centres on the trigger and
 * slides into view.
 */
function besideRule(side: 'start' | 'end'): string {
  return `@position-try ${besideRuleName(side)}{position-area:${areaFor(side)};${placementMargins(side)}${alignmentMargins(side)}inline-size:max-content;align-self:normal;justify-self:${anchorClearAlignment(side)};}`;
}

/** The block size of the room on one block side: the area minus its margins. */
function roomCap(gutter: string): string {
  return `calc(100% - ${CLEARANCE} - ${gutter})`;
}

/**
 * Half of the room the trigger leaves on the block axis, minus one side's
 * margins and one pixel: a side whose room is at least this much is the
 * roomier side. The pixel lets both sides fit when the trigger sits at the
 * viewport's middle, where rounding could otherwise fail both.
 */
function halfRoom(viewport: string, gutter: string): string {
  return `calc((${viewport} - anchor-size(block)) / 2 - ${CLEARANCE} - ${gutter} - 1px)`;
}

/**
 * `fit`: the slide's geometry on a block side, sized to the room on that
 * side; the layer scrolls what does not fit (FR3). It is at least half of the
 * room the trigger leaves, so it overflows, and does not fit, on the side
 * with less room.
 */
function fitRule(side: 'above' | 'below'): string {
  const size = (viewport: string, gutter: string) =>
    `max(${roomCap(gutter)}, ${halfRoom(viewport, gutter)})`;
  const blockSize = pair(
    'block-size',
    size('100vh', layerViewportInset.gutterBlockFallback),
    size('100dvb', layerViewportInset.gutterBlock),
  );
  return `@position-try ${fitRuleName(side)}{position-area:${areaFor(side)};${placementMargins(side)}${alignmentMargins(side)}${blockSize}align-self:${anchorClearAlignment(side)};}`;
}

/**
 * The one combined fallback list of an above or below layer that must never
 * settle over its anchor (FR4). After the layer's own position (the preferred
 * block side, at its own size): the opposite block side at its own size, then
 * beside the trigger on the inline end, then the inline start, and only then
 * the preferred block side and the opposite one sized to the room there, each
 * only while it is the roomier side. Every option before the last two keeps
 * the layer at its own size, so a layer whose content fits somewhere is never
 * stretched to a room; the last two are for content taller than the room on
 * both sides. Chromium tries no more than five options, so this replaces the
 * standard list rather than extending it. Side placements already slide along
 * the block axis at full height, so they have none.
 */
export function getAnchorClearFallbacks(placement: LayerPlacement): string {
  if (placement !== 'above' && placement !== 'below') {
    return '';
  }
  const opposite = placement === 'above' ? 'below' : 'above';
  return `flip-block, ${besideRuleName('end')}, ${besideRuleName('start')}, ${fitRuleName(placement)}, ${fitRuleName(opposite)}`;
}

/**
 * Every slide rule, for every placement and alignment, and the beside and fit
 * rules.
 */
export function slideRulesCss(): string {
  return [
    ...PLACEMENTS.flatMap(placement =>
      ALIGNMENTS.flatMap(alignment => [
        rule(placement, alignment, 'same'),
        rule(placement, alignment, 'opposite'),
      ]),
    ),
    besideRule('end'),
    besideRule('start'),
    fitRule('above'),
    fitRule('below'),
  ].join('');
}

export const SLIDE_RULES_ID = 'astryx-layer-slide-rules';

/**
 * Install the slide rules in a document once. Idempotent; a second layer, or
 * a layer in another document (an iframe), finds or adds its own sheet.
 */
export function ensureSlideRules(doc: Document): void {
  if (doc.getElementById(SLIDE_RULES_ID)) {
    return;
  }
  const style = doc.createElement('style');
  style.id = SLIDE_RULES_ID;
  style.textContent = slideRulesCss();
  doc.head.appendChild(style);
}