safe-area

import type {ReactNode} from "react";
import {Fill, Easing, interpolate, useBrand, useFrame, useDesignScale, useLayout} from "odori";

export type SafeAreaGuidesProps = {
  children?: ReactNode;
  /** Draw the title and action boundaries. */
  guides?: boolean;
  /** Extra inset beyond the layout policy, in design pixels. */
  inset?: number;
  label?: string;
};

/**
 * Keeps content inside the boundaries the layout declares, and can draw them.
 * The numbers come from the resolved layout, so a 9:16 cut gets the safety it
 * asked for rather than a value guessed at authoring time.
 */
export const SafeAreaGuides = ({children, guides = true, inset = 0, label = "safe area"}: SafeAreaGuidesProps) => {
  const frame = useFrame();
  const brand = useBrand();
  const scale = useDesignScale();
  const layout = useLayout();
  const safe = layout.safeArea ?? {x: 80, y: 80};
  const x = (safe.x + inset) * scale;
  const y = (safe.y + inset) * scale;
  const appear = interpolate(frame, [0, 18], [0, 1], {easing: Easing.standard});

  return (
    <Fill>
      <Fill
        style={{
          alignItems: "center",
          justifyContent: "center",
          padding: `${y}px ${x}px`,
          textAlign: "center",
        }}
      >
        {children}
      </Fill>
      {guides ? (
        <Fill style={{opacity: appear, pointerEvents: "none"}}>
          <div
            style={{
              border: `${2 * scale}px solid ${brand.colors.accent}`,
              inset: 0,
              margin: `${y}px ${x}px`,
              opacity: 0.55,
              position: "absolute",
            }}
          />
          <span
            style={{
              color: brand.colors.muted,
              fontFamily: brand.typography.mono,
              fontSize: 22 * scale,
              left: x,
              position: "absolute",
              top: Math.max(0, y - 34 * scale),
            }}
          >
            {label} · {Math.round(safe.x + inset)} x {Math.round(safe.y + inset)}
          </span>
        </Fill>
      ) : null}
    </Fill>
  );
};

import {defineComponentPreview} from "odori/preview";
import {SafeAreaGuides} from "./safe-area";

export default defineComponentPreview({
  title: "Safe area",
  category: "Foundation",
  description: "Format-aware title and action safety boundaries.",
  component: SafeAreaGuides,
  canvas: {width: 1920, height: 1080, duration: "3s"},
  controls: {
    guides: {type: "boolean", defaultValue: true},
    inset: {type: "number", defaultValue: 0, min: 0, max: 160},
    label: {type: "text", defaultValue: "safe area"},
  },
  examples: [
    {name: "Guides", props: {guides: true, children: "Everything readable sits inside"}},
    {name: "Composed", props: {guides: false, children: "Everything readable sits inside"}},
  ],
});

import {Scene, Video} from "odori";
import {SafeArea} from "../components/safe-area/safe-area";

<Video>
  <Scene id="safe-area" duration="3s">
    <SafeArea
      guides={true}
      inset={0}
      label="safe area"
    />
  </Scene>
</Video>