@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/safe-area/Overlay.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useRef } from 'react';
+import { BottomInsetContext } from './SafeAreaInset.js';
+// Overlay content is already inside the parent's reduced safe area. Its descendants consume
+// only their own local insets and inherit the parent's keyboard transform.
+const CONTENT_SCOPE = { consumed: true };
+/** An overlay in SafeAreaInset shares its reduced safe area and keyboard carrier with the composer. */
+export function Overlay({ alignment = 'center', content, children, ...props }) {
+    const { geometry, consumed } = useContext(BottomInsetContext);
+    const layer = useRef(null);
+    useLayoutEffect(() => {
+        if (layer.current)
+            return geometry?.attach(layer.current);
+    }, [geometry, alignment]);
+    const vertical = alignment.startsWith('top')
+        ? 'start'
+        : alignment.startsWith('bottom')
+            ? 'end'
+            : 'center';
+    const horizontal = alignment.toLowerCase().endsWith('leading')
+        ? 'start'
+        : alignment.toLowerCase().endsWith('trailing')
+            ? 'end'
+            : 'center';
+    return (_jsxs("div", { ...props, "data-satin-overlay": "true", children: [children, _jsx("div", { ref: layer, "data-satin-overlay-layer": alignment, "data-satin-overlay-inset": consumed || undefined, style: { alignItems: vertical, justifyItems: horizontal }, children: _jsx("div", { "data-satin-overlay-content": "true", children: _jsx(BottomInsetContext, { value: CONTENT_SCOPE, children: content }) }) })] }));
+}

package/dist/safe-area/SafeAreaInset.d.ts

@@ -0,0 +1,25 @@
+import { createBottomInsetGeometry } from './bottomInsetGeometry.js';
+import { type HTMLAttributes, type ReactNode } from 'react';
+/** Whether an enclosing SafeAreaInset already owns the bottom boundary (keyboard, home indicator). */
+export declare const BottomInsetContext: import("react").Context<{
+    consumed: boolean;
+    geometry?: ReturnType<typeof createBottomInsetGeometry>;
+}>;
+/** `VerticalEdge`/`HorizontalEdge`: `leading` and `trailing` follow the layout direction. */
+export type SafeAreaInsetEdge = 'top' | 'bottom' | 'leading' | 'trailing';
+/** The edge, the accessory (`content`) and its spacing; `children` is the content it insets. */
+export type SafeAreaInsetProps = Omit<HTMLAttributes<HTMLDivElement>, 'content'> & Readonly<{
+    edge: SafeAreaInsetEdge;
+    content: ReactNode;
+    spacing?: number;
+}>;
+/**
+ * `safeAreaInset(edge:spacing:content:)`. The accessory takes room from the content's safe
+ * area on its edge; a scroll view inside still spans the whole frame and scrolls under it.
+ *
+ * Bottom: content can scroll under the accessory; its terminal anchor clears it.
+ * The accessory's height reaches the content's scroll inset in the same frame it changes (CSS
+ * `--satin-inset-accessory-height`, written by its resize observer), so a composer that grows by
+ * a line keeps the newest message above it with no frame between.
+ */
+export declare function SafeAreaInset({ edge, content, spacing, children, ...props }: SafeAreaInsetProps): import("react").JSX.Element;

package/dist/safe-area/SafeAreaInset.js

@@ -0,0 +1,138 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createBottomInsetGeometry } from './bottomInsetGeometry.js';
+import { installKeyboardCarrier } from './keyboardCarrier.js';
+import { editable } from '../keyboard/adapter.js';
+import { IgnoresSafeAreaContext } from './context.js';
+import { createContext, useContext, useLayoutEffect, useRef, useMemo, useCallback, } from 'react';
+/** Whether an enclosing SafeAreaInset already owns the bottom boundary (keyboard, home indicator). */
+export const BottomInsetContext = createContext({ consumed: false });
+/** SwiftUI's system spacing between content and a safe-area inset (`spacing: nil`). */
+const SYSTEM_INSET_SPACING_PX = 8;
+const ACCESSORY_INSET_SCOPE = { consumed: true };
+/**
+ * `safeAreaInset(edge:spacing:content:)`. The accessory takes room from the content's safe
+ * area on its edge; a scroll view inside still spans the whole frame and scrolls under it.
+ *
+ * Bottom: content can scroll under the accessory; its terminal anchor clears it.
+ * The accessory's height reaches the content's scroll inset in the same frame it changes (CSS
+ * `--satin-inset-accessory-height`, written by its resize observer), so a composer that grows by
+ * a line keeps the newest message above it with no frame between.
+ */
+export function SafeAreaInset({ edge, content, spacing = SYSTEM_INSET_SPACING_PX, children, ...props }) {
+    if (edge !== 'bottom')
+        return (_jsx(EdgeInset, { ...props, edge: edge, content: content, spacing: spacing, children: children }));
+    return (_jsx(BottomInset, { ...props, content: content, spacing: spacing, children: children }));
+}
+function BottomInset({ content, spacing, children, ...props }) {
+    const edge = 'bottom';
+    const geometry = useMemo(createBottomInsetGeometry, []);
+    const scope = useMemo(() => ({ consumed: true, geometry }), [geometry]);
+    const contentElement = useRef(null);
+    const parent = useContext(BottomInsetContext);
+    const measuredHeight = useRef(0);
+    const systemInset = useRef(0);
+    const publish = useCallback((measuredExtension) => {
+        const content = contentElement.current;
+        if (!content)
+            return;
+        // Read the resolved system extension, not a registered property whose value
+        // WebKit can retain from the previous resize. Accessory height does not change it.
+        const extension = measuredExtension ?? (-Number.parseFloat(getComputedStyle(content).marginBottom) || 0);
+        geometry.publish((parent.geometry?.value ?? 0) + measuredHeight.current + spacing + extension);
+    }, [geometry, parent.geometry, spacing]);
+    // `IgnoresSafeArea regions="keyboard"` around the inset: the boundary stays above the home
+    // indicator while the keyboard is up, as SwiftUI's `ignoresSafeArea(.keyboard)`.
+    const keyboardIgnored = useContext(IgnoresSafeAreaContext).keyboard;
+    const inset = useRef(null);
+    const accessory = useRef(null);
+    useLayoutEffect(() => {
+        const host = inset.current;
+        const element = accessory.current;
+        if (!host || !element)
+            return;
+        const measure = () => {
+            const property = '--satin-inset-accessory-height';
+            measuredHeight.current = element.getBoundingClientRect().height;
+            const height = `${measuredHeight.current}px`;
+            const content = contentElement.current;
+            // Finish geometry reads before the height write invalidates the transcript's layout.
+            const extension = content
+                ? -Number.parseFloat(getComputedStyle(content).marginBottom) || 0
+                : 0;
+            systemInset.current = extension;
+            if (host.style.getPropertyValue(property) !== height)
+                host.style.setProperty(property, height);
+            publish(extension);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        // System padding and the content extension can cancel in the scrollport size.
+        // The boundary content box still changes, so it must be observed as well.
+        observer.observe(host);
+        // Rotation, keyboard avoidance and tab coverage can change the system contribution too.
+        if (contentElement.current)
+            observer.observe(contentElement.current);
+        return () => observer.disconnect();
+    }, [publish]);
+    useLayoutEffect(() => {
+        if (inset.current)
+            return parent.geometry?.attach(inset.current, publish, geometry);
+    }, [parent.geometry, publish, geometry]);
+    useLayoutEffect(publish, [publish, spacing]);
+    // The root boundary moves with the keyboard on the compositor (keyboardCarrier.ts). A TabView's
+    // boundary keeps its tab bar behind the keyboard and only pads its content cell: not carried.
+    const carried = !parent.consumed && !keyboardIgnored;
+    useLayoutEffect(() => {
+        const host = inset.current;
+        const element = accessory.current;
+        if (!carried || !host || !element)
+            return;
+        if (host.parentElement?.hasAttribute('data-satin-tab-view'))
+            return;
+        return installKeyboardCarrier(host, element, geometry, () => ({
+            systemInset: systemInset.current,
+            accessoryHeight: measuredHeight.current,
+            // Tab-hosted boundaries own covered rows and are excluded above.
+            coveredRows: 0,
+        }));
+    }, [carried, geometry]);
+    // Native controls never end editing. WebKit moves focus at a press's mouse-down, so a press on
+    // an accessory control (Send) would take the keyboard down with the field beside it.
+    const keepEditing = (event) => {
+        if (editable(document.activeElement) && !editable(event.target))
+            event.preventDefault();
+    };
+    return (_jsx("div", { ...props, style: { ...props.style, ['--satin-inset-spacing']: `${spacing}px` }, ref: inset, "data-satin-safe-area-inset": edge, "data-satin-bottom-boundary": parent.consumed ? 'nested' : 'root', "data-satin-keyboard-ignored": keyboardIgnored || undefined, children: _jsxs(BottomInsetContext, { value: scope, children: [_jsx("div", { ref: contentElement, "data-satin-inset-content": "true", children: children }), _jsx(BottomInsetContext, { value: ACCESSORY_INSET_SCOPE, children: _jsx("div", { ref: accessory, "data-satin-inset-accessory": "true", onMouseDown: keepEditing, children: content }) })] }) }));
+}
+/*
+ * Top, leading and trailing insets join the same chain as the bottom one:
+ * - top: the accessory sits at the safe area's top edge (below the bar, or below a large title)
+ *   and adds its height plus `spacing` to the content's top inset (`--satin-scroll-inset-top`), as
+ *   native adds it to the scroll view's adjusted inset (iOS 27 native reference `inset-top`: 116 + 44.33 + 8);
+ * - leading/trailing: the accessory is a column of the safe area's height and the content's frame
+ *   gives up its width plus `spacing` (`inset-leading`: strip 0–60, cards from 68).
+ * A background drawn by the accessory's root view reaches the screen's top edge, as a SwiftUI
+ * `background` ignores the safe area by default (`inset-top`: the yellow fills 0–160.33).
+ */
+function EdgeInset({ edge, content, spacing, children, ...props }) {
+    const accessory = useRef(null);
+    const inset = useRef(null);
+    const bottom = useContext(BottomInsetContext);
+    useLayoutEffect(() => {
+        if (edge !== 'top' && accessory.current)
+            return bottom.geometry?.attach(accessory.current);
+    }, [bottom.geometry, edge]);
+    useLayoutEffect(() => {
+        const host = inset.current;
+        const element = accessory.current;
+        if (!host || !element || edge !== 'top')
+            return;
+        const measure = () => host.style.setProperty('--satin-inset-accessory-height', `${element.getBoundingClientRect().height}px`);
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [edge]);
+    return (_jsxs("div", { ...props, style: { ...props.style, ['--satin-inset-spacing']: `${spacing}px` }, ref: inset, "data-satin-safe-area-inset": edge, children: [_jsx("div", { "data-satin-inset-content": "true", children: children }), _jsx("div", { ref: accessory, "data-satin-inset-accessory": edge, children: content })] }));
+}

package/dist/safe-area/bottomInsetGeometry.d.ts

@@ -0,0 +1,12 @@
+/** Published after a scroll surface receives its new terminal inset. */
+export declare const BOTTOM_INSET_CHANGED = "satin-bottom-inset-changed";
+export type BottomInsetGeometry = Readonly<{
+    value: number;
+    attached(): ReadonlySet<HTMLElement>;
+    participants(): ReadonlySet<HTMLElement>;
+    publish(next: number): void;
+    subscribeParticipants(changed: () => void): () => void;
+    attach(element: HTMLElement, changed?: () => void, descendants?: BottomInsetGeometry): () => void;
+}>;
+/** Deliver an inset only to layout owners, without invalidating every message in a scroll view. */
+export declare function createBottomInsetGeometry(): BottomInsetGeometry;

package/dist/safe-area/bottomInsetGeometry.js

@@ -0,0 +1,73 @@
+/** Published after a scroll surface receives its new terminal inset. */
+export const BOTTOM_INSET_CHANGED = 'satin-bottom-inset-changed';
+/** Deliver an inset only to layout owners, without invalidating every message in a scroll view. */
+export function createBottomInsetGeometry() {
+    let value = 0;
+    const consumers = new Set();
+    const elements = new Set();
+    const nested = new Set();
+    const participantListeners = new Set();
+    const participantsChanged = () => {
+        for (const changed of participantListeners)
+            changed();
+    };
+    return {
+        get value() {
+            return value;
+        },
+        /** The elements laid out inside this inset: its scroll views, nested insets and accessories. */
+        attached() {
+            return elements;
+        },
+        participants() {
+            return new Set([
+                ...elements,
+                ...[...nested].flatMap(geometry => [...geometry.participants()]),
+            ]);
+        },
+        subscribeParticipants(changed) {
+            participantListeners.add(changed);
+            return () => {
+                participantListeners.delete(changed);
+            };
+        },
+        publish(next) {
+            if (!Number.isFinite(next) || next === value)
+                return;
+            value = next;
+            for (const consume of consumers)
+                consume(value);
+        },
+        attach(element, changed, descendants) {
+            const property = '--satin-scroll-inset-bottom';
+            const previous = element.style.getPropertyValue(property);
+            const consume = (inset) => {
+                const next = `${inset}px`;
+                if (element.style.getPropertyValue(property) === next)
+                    return;
+                element.style.setProperty(property, next);
+                changed?.();
+                element.dispatchEvent(new Event(BOTTOM_INSET_CHANGED));
+            };
+            consumers.add(consume);
+            elements.add(element);
+            consume(value);
+            if (descendants)
+                nested.add(descendants);
+            const unsubscribe = descendants?.subscribeParticipants(participantsChanged);
+            participantsChanged();
+            return () => {
+                consumers.delete(consume);
+                elements.delete(element);
+                unsubscribe?.();
+                if (descendants)
+                    nested.delete(descendants);
+                if (previous)
+                    element.style.setProperty(property, previous);
+                else
+                    element.style.removeProperty(property);
+                participantsChanged();
+            };
+        },
+    };
+}

package/dist/safe-area/context.d.ts

@@ -0,0 +1,15 @@
+/** `Edge`. `leading` and `trailing` follow the layout direction. */
+export type Edge = 'top' | 'bottom' | 'leading' | 'trailing';
+/** `EdgeInsets` in points, by layout direction. */
+export type EdgeLengths = Readonly<Partial<Record<Edge, number>>>;
+export type Lengths = Readonly<Record<Edge, number>>;
+export declare const NO_LENGTHS: Lengths;
+/** Safe-area padding the enclosing modifiers add to the next scroll view's content, per edge. */
+export declare const SafeAreaPaddingContext: import("react").Context<Readonly<Record<Edge, number>>>;
+/** `contentMargins(for: .scrollContent)` in effect for every scroll view below, per edge. */
+export declare const ContentMarginsContext: import("react").Context<Readonly<Partial<Record<Edge, number>>>>;
+/** The safe-area regions and edges an enclosing `IgnoresSafeArea` gives up. */
+export declare const IgnoresSafeAreaContext: import("react").Context<{
+    container: ReadonlySet<Edge>;
+    keyboard: boolean;
+}>;

package/dist/safe-area/context.js

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+export const NO_LENGTHS = { top: 0, bottom: 0, leading: 0, trailing: 0 };
+/** Safe-area padding the enclosing modifiers add to the next scroll view's content, per edge. */
+export const SafeAreaPaddingContext = createContext(NO_LENGTHS);
+/** `contentMargins(for: .scrollContent)` in effect for every scroll view below, per edge. */
+export const ContentMarginsContext = createContext({});
+/** The safe-area regions and edges an enclosing `IgnoresSafeArea` gives up. */
+export const IgnoresSafeAreaContext = createContext({ container: new Set(), keyboard: false });

package/dist/safe-area/displayCorners.d.ts

@@ -0,0 +1,21 @@
+/** Display geometry in CSS points. Supply the physical screen, not the app window. */
+export type DisplayGeometry = Readonly<{
+    width: number;
+    height: number;
+    scale: number;
+}>;
+/** The screen's corner radius in points, with how sure Satin is of the model. */
+export type DisplayCornerMetrics = Readonly<{
+    /** Minimum measured radius when resolution cannot distinguish models. Unknown displays use zero. */
+    radius: number;
+    range: readonly [minimum: number, maximum: number];
+    source: 'exact' | 'ambiguous' | 'fallback';
+}>;
+/** Resolution is not a model identifier. Unknown and asymmetric displays use the scalar fallback. */
+export declare function resolveDisplayCornerMetrics(display: DisplayGeometry): DisplayCornerMetrics;
+/** Framework token for the screen containing this app. Display Zoom and unknown models fall back to zero. */
+export declare function readDisplayCornerMetrics(): DisplayCornerMetrics;
+/** Updates after rotation, window moves and DPR changes announced by a resize. */
+export declare function useDisplayCornerRadius(): number;
+/** Radius for a shape inset equally from a rounded container. Insets consume, never invert, corners. */
+export declare function concentricRadius(containerRadius: number, inset: number): number;

package/dist/safe-area/displayCorners.js

@@ -0,0 +1,70 @@
+import { useLayoutEffect, useState } from 'react';
+// Derived Xcode 27 device-profile display geometry, 2026-10-10. No private API ships.
+// See the implementation contract for model collisions and measurement limits.
+const displayRadii = {
+    '402x874@3': [62, 62],
+    '440x956@3': [62, 62],
+    '390x844@3': [47, 47.33333206],
+    '420x912@3': [62, 62],
+    '393x852@3': [55, 55],
+    '430x932@3': [55, 55],
+    '428x926@3': [53, 53.33333206],
+    '360x780@3': [44, 44],
+    '375x812@3': [39, 39],
+    '414x896@3': [39, 39],
+    '414x896@2': [41.5, 41.5],
+    '1032x1376@2': [30, 30],
+    '834x1210@2': [30, 30],
+    '1024x1366@2': [0, 18],
+    '820x1180@2': [18, 25],
+    '744x1133@2': [21.5, 21.5],
+    '834x1194@2': [18, 18],
+    '810x1080@2': [0, 0],
+    '834x1112@2': [0, 18],
+    '768x1024@2': [0, 0],
+};
+/** Resolution is not a model identifier. Unknown and asymmetric displays use the scalar fallback. */
+export function resolveDisplayCornerMetrics(display) {
+    const width = Math.min(display.width, display.height);
+    const height = Math.max(display.width, display.height);
+    const range = displayRadii[`${width}x${height}@${display.scale}`];
+    if (!range)
+        return { radius: 0, range: [0, 0], source: 'fallback' };
+    return {
+        radius: range[0],
+        range: [range[0], range[1]],
+        source: range[0] === range[1] ? 'exact' : 'ambiguous',
+    };
+}
+/** Framework token for the screen containing this app. Display Zoom and unknown models fall back to zero. */
+export function readDisplayCornerMetrics() {
+    return resolveDisplayCornerMetrics({
+        width: window.screen.width,
+        height: window.screen.height,
+        scale: window.devicePixelRatio,
+    });
+}
+/** Updates after rotation, window moves and DPR changes announced by a resize. */
+export function useDisplayCornerRadius() {
+    const [radius, setRadius] = useState(() => readDisplayCornerMetrics().radius);
+    useLayoutEffect(() => {
+        const update = () => setRadius(readDisplayCornerMetrics().radius);
+        update();
+        window.addEventListener('resize', update);
+        window.addEventListener('orientationchange', update);
+        return () => {
+            window.removeEventListener('resize', update);
+            window.removeEventListener('orientationchange', update);
+        };
+    }, []);
+    return radius;
+}
+/** Radius for a shape inset equally from a rounded container. Insets consume, never invert, corners. */
+export function concentricRadius(containerRadius, inset) {
+    if (!Number.isFinite(containerRadius) ||
+        containerRadius < 0 ||
+        !Number.isFinite(inset) ||
+        inset < 0)
+        throw new Error('Concentric corners require finite, nonnegative radius and inset.');
+    return Math.max(0, containerRadius - inset);
+}

package/dist/safe-area/keyboardCarrier.d.ts

@@ -0,0 +1,26 @@
+import type { BottomInsetGeometry } from './bottomInsetGeometry.js';
+/**
+ * Moves a root bottom inset with the software keyboard as one thing, as a native chat's composer
+ * and transcript ride the keyboard.
+ *
+ * Why not animate the inset's padding: that is layout, and layout needs the page to draw. On the
+ * installed iPad WebKit draws one page frame after it reports the keyboard and then none until the
+ * keyboard has arrived (~390 ms on the tested iPad). A padding animation stands still for
+ * that whole time and then jumps. Transform animations run on the compositor and keep moving.
+ *
+ * So each keyboard change is one run on the keyboard's own curve (keyboard/motion.ts):
+ * - the accessory (the composer) and the content of each scroll view that is pinned to its bottom
+ *   (`defaultScrollAnchor="bottom"`) move together on compositor transforms;
+ * - the inset's layout changes once per run, at the endpoint where nothing is clipped. A keyboard
+ *   that rises keeps the taller scrollport until the composer has arrived, then commits the shorter
+ *   one; a keyboard that falls commits the taller one first and the transforms lead back to it.
+ *   Committing a shorter scrollport first would clip the transcript above the composer.
+ * - a run that starts while another is moving starts from the pose on screen, never from rest.
+ *
+ * The editor stays live and keeps its text, selection and focus: nothing is snapshotted or scaled.
+ */
+export declare function installKeyboardCarrier(boundary: HTMLElement, accessory: HTMLElement, geometry: BottomInsetGeometry, measuredRoom: () => Readonly<{
+    systemInset: number;
+    coveredRows: number;
+    accessoryHeight: number;
+}>): () => void;