@drawnagency/primitives 0.1.111 → 0.1.112

package/src/deck/media.tsx

@@ -0,0 +1,46 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import type { DeckMediaAsset, DeckMediaRef, DeckMediaResolver } from "../schemas/deck";
+
+/**
+ * The runtime's media seam.
+ *
+ * Deck JSON stores references, never URLs (ADR 0001), so something outside the
+ * runtime has to turn `{ kind: "portal", id }` into bytes. That something is a
+ * resolver injected through context: the Deck Builder passes the manifest-backed
+ * one, the dev preview route passes placeholders, and the components below never
+ * learn which. Absent a provider every reference resolves to `null`, which is
+ * also what a deleted asset resolves to — one path, one rendering.
+ */
+
+export type { DeckMediaAsset, DeckMediaResolver } from "../schemas/deck";
+
+const NO_MEDIA: DeckMediaResolver = () => null;
+
+const DeckMediaContext = createContext<DeckMediaResolver>(NO_MEDIA);
+
+export function DeckMediaProvider({ resolve, children }: { resolve: DeckMediaResolver; children: ReactNode }) {
+  return <DeckMediaContext.Provider value={resolve}>{children}</DeckMediaContext.Provider>;
+}
+
+export function useDeckMedia(ref: DeckMediaRef): DeckMediaAsset | null {
+  return useContext(DeckMediaContext)(ref);
+}
+
+/**
+ * The resolver itself, for a component that has to resolve a whole set before
+ * it can lay any of it out — the image grid packs its masonry columns from
+ * every tile's aspect ratio, which it cannot learn one `useDeckMedia` at a time.
+ */
+export function useDeckMediaResolver(): DeckMediaResolver {
+  return useContext(DeckMediaContext);
+}
+
+/**
+ * What an unresolvable reference renders. A published deck can outlive the
+ * media it points at (ADR 0002 flags the GC hazard), and a torn alt string over
+ * a presentation is worse than a quiet gap.
+ */
+export function DeckMissingMedia({ className }: { className?: string }) {
+  return <span data-deck-media="missing" aria-hidden="true" className={cn("block size-full bg-base-200", className)} />;
+}

package/src/deck/tokens.ts

@@ -0,0 +1,57 @@
+import type { CSSProperties } from "react";
+import type { DeckSurface } from "../schemas/deck";
+
+export type { DeckSurface } from "../schemas/deck";
+
+/**
+ * Deck ink is indirected through three custom properties so a Deck Component
+ * never has to know what it is sitting on: a Layout declares the palette for
+ * its surface, components read `--deck-ink` / `--deck-ink-muted` /
+ * `--deck-accent`. Every value resolves to a portal brand token — nothing in
+ * the deck runtime carries a literal color.
+ */
+const SURFACE_INK: Record<DeckSurface, CSSProperties> = {
+  base: {
+    "--deck-ink": "var(--color-base-contrast)",
+    "--deck-ink-muted": "var(--color-base-contrast-light)",
+    "--deck-accent": "var(--color-primary)",
+  } as CSSProperties,
+  brand: {
+    "--deck-ink": "var(--color-on-primary)",
+    "--deck-ink-muted": "color-mix(in srgb, var(--color-on-primary) 72%, transparent)",
+    "--deck-accent": "var(--color-primary-contrast)",
+  } as CSSProperties,
+};
+
+export function surfaceInk(surface: DeckSurface): CSSProperties {
+  return SURFACE_INK[surface];
+}
+
+/** Tailwind background utility for a surface — both are brand tokens. */
+export const SURFACE_BACKGROUND: Record<DeckSurface, string> = {
+  base: "bg-base-accent",
+  brand: "bg-primary",
+};
+
+/**
+ * Alignment travels the same way the ink does: a Layout declares how its slot
+ * reads, components resolve `--deck-align` (an `align-self` value). Without it
+ * a component would have to know whether it sits on a centered title card or in
+ * a left-aligned column, which is precisely what the indirection prevents.
+ */
+export type DeckAlign = "center" | "start";
+
+export function deckAlign(align: DeckAlign): CSSProperties {
+  return { "--deck-align": align } as CSSProperties;
+}
+
+/**
+ * Elevation for media that lifts off the slide — grid tiles on hover, the video
+ * play affordance. Declared as `--deck-*` custom properties rather than as
+ * arbitrary Tailwind values so the shadow can be mixed from the site's ink
+ * token instead of a literal rgba, and so a hover variant can reference it.
+ */
+export const DECK_ELEVATION: CSSProperties = {
+  "--deck-lift": "0 26px 46px -18px color-mix(in srgb, var(--color-base-contrast) 45%, transparent)",
+  "--deck-lift-strong": "0 30px 60px -22px color-mix(in srgb, var(--color-base-contrast) 58%, transparent)",
+} as CSSProperties;

package/src/deck/useStageScale.ts

@@ -0,0 +1,44 @@
+import { useEffect, useLayoutEffect, useState, type RefObject } from "react";
+import { DECK_STAGE_HEIGHT, DECK_STAGE_WIDTH } from "../schemas/deck";
+
+/**
+ * The first measurement has to happen before paint or the stage shows one frame
+ * unscaled — a full-bleed 1600x900 flash on a laptop viewport. useLayoutEffect
+ * warns when React renders on the server (Astro SSRs this island), and there is
+ * nothing to measure there anyway, so fall back to useEffect off the browser.
+ */
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * The factor that fits the fixed 1600x900 stage inside `fitRef`'s box.
+ *
+ * `null` until the box has been measured — an unmeasured box (SSR, jsdom, a
+ * hidden ancestor) reports 0x0, and scaling the stage to 0 would blank it. The
+ * caller renders the stage unscaled until a real measurement arrives.
+ */
+export function useStageScale(fitRef: RefObject<HTMLElement | null>): number | null {
+  const [scale, setScale] = useState<number | null>(null);
+
+  useIsomorphicLayoutEffect(() => {
+    const el = fitRef.current;
+    if (!el) return;
+
+    const measure = () => {
+      const { clientWidth, clientHeight } = el;
+      if (!clientWidth || !clientHeight) return;
+      setScale(Math.min(clientWidth / DECK_STAGE_WIDTH, clientHeight / DECK_STAGE_HEIGHT));
+    };
+
+    measure();
+
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", measure);
+      return () => window.removeEventListener("resize", measure);
+    }
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [fitRef]);
+
+  return scale;
+}