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

package/dist/text-input/focusChain.js

@@ -0,0 +1,62 @@
+import { useMemo } from 'react';
+/** Explicit order survives conditional rendering; disabled/unmounted fields are skipped. */
+export function createFocusChain(order) {
+    if (new Set(order).size !== order.length)
+        throw new Error('Focus chain keys must be unique.');
+    const fields = new Map();
+    const bindings = new Map(order.map(key => [
+        key,
+        {
+            ref: (element) => {
+                if (element)
+                    fields.set(key, element);
+                else
+                    fields.delete(key);
+            },
+            onSubmit: () => next(key),
+        },
+    ]));
+    const available = (field) => Boolean(field?.isConnected &&
+        !field.disabled &&
+        !field.readOnly &&
+        !field.closest('[inert], [hidden]'));
+    function next(key) {
+        for (const candidate of order.slice(order.indexOf(key) + 1)) {
+            const field = fields.get(candidate);
+            if (available(field)) {
+                field.focus({ preventScroll: true });
+                return;
+            }
+        }
+        fields.get(key)?.blur();
+    }
+    return {
+        field(key) {
+            const binding = bindings.get(key);
+            if (!binding)
+                throw new Error(`Unknown focus chain key: ${key}`);
+            return binding;
+        },
+        focus(key) {
+            const field = fields.get(key);
+            if (available(field))
+                field.focus({ preventScroll: true });
+        },
+        dismiss() {
+            for (const field of fields.values())
+                field.blur();
+        },
+    };
+}
+/**
+ * `@FocusState` for a form: the return key moves to the next field in `order` and the
+ * last one dismisses the keyboard. Spread `field(key)` onto each field.
+ *
+ * @example
+ * const focus = useFocusChain(['name', 'email'])
+ * <TextField label="Name" {...focus.field('name')} value={name} onChange={setName} />
+ */
+export function useFocusChain(order) {
+    const identity = JSON.stringify(order);
+    return useMemo(() => createFocusChain(JSON.parse(identity)), [identity]);
+}

package/dist/text-input/kinds.d.ts

@@ -0,0 +1,8 @@
+import type { InputHTMLAttributes } from 'react';
+/** What a field holds, setting its keyboard, autofill and autocorrection together. */
+export type TextFieldKind = 'text' | 'name' | 'email' | 'url' | 'tel' | 'number' | 'decimal' | 'search' | 'username' | 'new-password' | 'current-password' | 'one-time-code';
+/** `SubmitLabel`: the return key's title. */
+export type SubmitLabel = 'done' | 'go' | 'next' | 'search' | 'send';
+type Attributes = Pick<InputHTMLAttributes<HTMLInputElement>, 'type' | 'inputMode' | 'autoComplete' | 'autoCapitalize' | 'autoCorrect' | 'spellCheck' | 'enterKeyHint'>;
+export declare function textFieldAttributes(kind?: TextFieldKind, submitLabel?: SubmitLabel): Attributes;
+export {};

package/dist/text-input/kinds.js

@@ -0,0 +1,34 @@
+const plain = {
+    type: 'text',
+    inputMode: 'text',
+    autoComplete: 'off',
+    autoCapitalize: 'sentences',
+    autoCorrect: 'on',
+    spellCheck: true,
+    enterKeyHint: 'done',
+};
+const literal = {
+    ...plain,
+    autoCapitalize: 'none',
+    autoCorrect: 'off',
+    spellCheck: false,
+};
+const kinds = {
+    text: plain,
+    name: { ...plain, autoComplete: 'name', autoCapitalize: 'words', spellCheck: false },
+    email: { ...literal, type: 'email', inputMode: 'email', autoComplete: 'email' },
+    url: { ...literal, type: 'url', inputMode: 'url', autoComplete: 'url', enterKeyHint: 'go' },
+    tel: { ...literal, type: 'tel', inputMode: 'tel', autoComplete: 'tel' },
+    // Strings preserve leading zeros and incomplete decimal entry. Numeric HTML
+    // inputs sanitize values and do not support the normal selection API.
+    number: { ...literal, inputMode: 'numeric' },
+    decimal: { ...literal, inputMode: 'decimal' },
+    search: { ...plain, type: 'search', inputMode: 'search', enterKeyHint: 'search' },
+    username: { ...literal, autoComplete: 'username' },
+    'new-password': { ...literal, type: 'password', autoComplete: 'new-password' },
+    'current-password': { ...literal, type: 'password', autoComplete: 'current-password' },
+    'one-time-code': { ...literal, inputMode: 'numeric', autoComplete: 'one-time-code' },
+};
+export function textFieldAttributes(kind = 'text', submitLabel) {
+    return { ...kinds[kind], ...(submitLabel ? { enterKeyHint: submitLabel } : {}) };
+}

package/dist/text-input/measureEditor.d.ts

@@ -0,0 +1,2 @@
+/** Measure wrapping without resizing, selecting, or scrolling the live editing control. */
+export declare function measureEditorContentHeight(editor: HTMLTextAreaElement): number;

package/dist/text-input/measureEditor.js

@@ -0,0 +1,50 @@
+import { EDITOR_TEXT_LAYOUT_PROPERTIES } from './editorTextLayout.js';
+/** Measure wrapping without resizing, selecting, or scrolling the live editing control. */
+export function measureEditorContentHeight(editor) {
+    const document = editor.ownerDocument;
+    const computed = getComputedStyle(editor);
+    const mirror = document.createElement('textarea');
+    mirror.setAttribute('aria-hidden', 'true');
+    mirror.tabIndex = -1;
+    mirror.inert = true;
+    mirror.wrap = editor.wrap;
+    mirror.value = editor.value;
+    mirror.placeholder = editor.placeholder;
+    const copy = [
+        ...EDITOR_TEXT_LAYOUT_PROPERTIES,
+        'white-space',
+        'padding',
+        'border-style',
+        'box-sizing',
+        'width',
+    ];
+    mirror.style.setProperty('all', 'initial', 'important');
+    for (const property of copy) {
+        mirror.style.setProperty(property, computed.getPropertyValue(property), 'important');
+    }
+    const isolation = {
+        position: 'fixed',
+        top: '0',
+        left: '0',
+        height: '0',
+        'min-height': '0',
+        'max-height': 'none',
+        'min-width': '0',
+        'max-width': 'none',
+        margin: '0',
+        visibility: 'hidden',
+        'pointer-events': 'none',
+        overflow: 'hidden',
+        resize: 'none',
+    };
+    for (const [property, value] of Object.entries(isolation)) {
+        mirror.style.setProperty(property, value, 'important');
+    }
+    document.body.append(mirror);
+    try {
+        return mirror.scrollHeight;
+    }
+    finally {
+        mirror.remove();
+    }
+}

package/dist/text-input/submit.d.ts

@@ -0,0 +1,9 @@
+/** Enter confirms an IME candidate before it can submit the field. */
+export declare function shouldSubmitField(event: {
+    key: string;
+    defaultPrevented: boolean;
+    keyCode: number;
+    nativeEvent: {
+        isComposing: boolean;
+    };
+}): boolean;

package/dist/text-input/submit.js

@@ -0,0 +1,7 @@
+/** Enter confirms an IME candidate before it can submit the field. */
+export function shouldSubmitField(event) {
+    return (!event.defaultPrevented &&
+        event.key === 'Enter' &&
+        !event.nativeEvent.isComposing &&
+        event.keyCode !== 229);
+}

package/dist/unstable.d.ts

@@ -0,0 +1,16 @@
+/** Low-level split composition. Prefer NavigationSplitView for application navigation. */
+export { Sidebar, type SidebarProps, type SidebarEntry } from './navigation/Sidebar.js';
+export { DetailList } from './navigation/DetailList.js';
+export { useSplitSelection } from './navigation/splitContext.js';
+/** Low-level sidebar artwork. Prefer SymbolImage for application symbols. */
+export { SidebarSymbol } from './navigation/SidebarSymbol.js';
+/** Experimental frame matching only. Ordinary React state changes do not animate. */
+export { MatchedGeometryEffect, type MatchedGeometryEffectProps, } from './motion/matchedGeometry.js';
+/** Compatibility exports. New apps import these stable APIs from `@satinhq/kit`. */
+export { withAnimation } from './motion/matchedGeometry.js';
+export { Animation, type SpringOptions } from './motion/animationValue.js';
+export { Transition, type TransitionEdge } from './motion/transition.js';
+export { TransitionView, type TransitionViewProps } from './motion/TransitionView.js';
+export { GestureView, type GestureViewProps } from './gestures/GestureView.js';
+export { DragGesture, LongPressGesture, TapGesture, MagnifyGesture, useGestureState, type Gesture, type GesturePoint, type GestureState, type DragGestureOptions, type DragGestureValue, type LongPressGestureOptions, type TapGestureOptions, type MagnifyGestureOptions, type MagnifyGestureValue, } from './gestures/gesture.js';
+export { concentricRadius, useDisplayCornerRadius } from './safe-area/displayCorners.js';

package/dist/unstable.js

@@ -0,0 +1,16 @@
+/** Low-level split composition. Prefer NavigationSplitView for application navigation. */
+export { Sidebar } from './navigation/Sidebar.js';
+export { DetailList } from './navigation/DetailList.js';
+export { useSplitSelection } from './navigation/splitContext.js';
+/** Low-level sidebar artwork. Prefer SymbolImage for application symbols. */
+export { SidebarSymbol } from './navigation/SidebarSymbol.js';
+/** Experimental frame matching only. Ordinary React state changes do not animate. */
+export { MatchedGeometryEffect, } from './motion/matchedGeometry.js';
+/** Compatibility exports. New apps import these stable APIs from `@satinhq/kit`. */
+export { withAnimation } from './motion/matchedGeometry.js';
+export { Animation } from './motion/animationValue.js';
+export { Transition } from './motion/transition.js';
+export { TransitionView } from './motion/TransitionView.js';
+export { GestureView } from './gestures/GestureView.js';
+export { DragGesture, LongPressGesture, TapGesture, MagnifyGesture, useGestureState, } from './gestures/gesture.js';
+export { concentricRadius, useDisplayCornerRadius } from './safe-area/displayCorners.js';

package/dist/vite.d.ts

@@ -0,0 +1,3 @@
+/** App build integration. Fixture tooling is available from satin/internal/vite. */
+export { satinApp, type SatinAppOptions } from './app/vite.js';
+export { defineApp } from './public/definition.js';

package/dist/vite.js

@@ -0,0 +1,3 @@
+/** App build integration. Fixture tooling is available from satin/internal/vite. */
+export { satinApp } from './app/vite.js';
+export { defineApp } from './public/definition.js';

package/dist/web/WebView.d.ts

@@ -0,0 +1,42 @@
+import { type CSSProperties } from 'react';
+export type WebFrameState = {
+    status: 'idle' | 'loading';
+} | {
+    status: 'loaded';
+    url: string;
+    title: string;
+} | {
+    status: 'unverified';
+    reason: 'cross-origin-or-denied';
+} | {
+    status: 'unavailable';
+    reason: 'invalid-url' | 'load-error';
+};
+export type WebFrameActionResult = {
+    status: 'dispatched';
+} | {
+    status: 'unavailable';
+    reason: 'not-mounted' | 'cross-origin-or-denied';
+};
+/** Only same-origin frames expose their current page or accept reload/stop commands. */
+export interface WebFrameController {
+    readonly state: WebFrameState;
+    reload(): WebFrameActionResult;
+    stop(): WebFrameActionResult;
+}
+/** Observe a WebView and request the operations its origin permits. */
+export declare function useWebFrame(): WebFrameController;
+export interface WebViewProps {
+    url: string;
+    /** Accessible name for the embedded page. */
+    title: string;
+    controller?: WebFrameController;
+    /** Explicitly allow scripts. Same-origin scripted content must be trusted. */
+    allowsJavaScript?: boolean;
+    allowsForms?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    onStateChange?: (state: WebFrameState) => void;
+}
+/** A sandboxed embedded page. Framing policy and partitioned storage remain browser-owned. */
+export declare function WebView({ url: input, title, controller, className, style, onStateChange, allowsJavaScript, allowsForms, }: WebViewProps): import("react").JSX.Element | null;

package/dist/web/WebView.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { webURL } from './urlPolicy.js';
+const stores = new WeakMap();
+function createFrameStore() {
+    let frame = null;
+    let state = { status: 'idle' };
+    const listeners = new Set();
+    const command = (action) => {
+        if (!frame?.contentWindow)
+            return { status: 'unavailable', reason: 'not-mounted' };
+        try {
+            if (!frame.contentDocument || frame.contentWindow.location.origin !== location.origin)
+                return { status: 'unavailable', reason: 'cross-origin-or-denied' };
+            action(frame.contentWindow);
+            return { status: 'dispatched' };
+        }
+        catch {
+            return { status: 'unavailable', reason: 'cross-origin-or-denied' };
+        }
+    };
+    const controller = {
+        get state() {
+            return state;
+        },
+        reload: () => command(window => window.location.reload()),
+        stop: () => command(window => window.stop()),
+    };
+    return {
+        controller,
+        getSnapshot: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setState(value) {
+            state = value;
+            listeners.forEach(listener => listener());
+        },
+        attach(value) {
+            if (frame && frame !== value)
+                throw new Error('A WebFrameController can own only one WebView');
+            frame = value;
+        },
+        detach(value) {
+            if (frame === value)
+                frame = null;
+        },
+    };
+}
+/** Observe a WebView and request the operations its origin permits. */
+export function useWebFrame() {
+    const store = useMemo(() => {
+        const value = createFrameStore();
+        stores.set(value.controller, value);
+        return value;
+    }, []);
+    useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    return store.controller;
+}
+/** A sandboxed embedded page. Framing policy and partitioned storage remain browser-owned. */
+export function WebView({ url: input, title, controller, className, style, onStateChange, allowsJavaScript = false, allowsForms = false, }) {
+    const local = useWebFrame();
+    const store = stores.get(controller ?? local);
+    if (!store)
+        throw new Error('Use useWebFrame to create a WebFrameController');
+    const ref = useRef(null);
+    const observer = useRef(onStateChange);
+    observer.current = onStateChange;
+    const url = webURL(input, typeof location === 'undefined' ? 'https://invalid.invalid/' : location.href);
+    const href = url?.href;
+    useEffect(() => {
+        const frame = ref.current;
+        if (frame)
+            store.attach(frame);
+        store.setState(href ? { status: 'loading' } : { status: 'unavailable', reason: 'invalid-url' });
+        observer.current?.(store.getSnapshot());
+        return () => {
+            if (frame)
+                store.detach(frame);
+        };
+    }, [href, store]);
+    const publish = (state) => {
+        store.setState(state);
+        observer.current?.(state);
+    };
+    if (!href)
+        return null;
+    return (_jsx("iframe", { ref: ref, src: href, title: title, className: className, style: { border: 0, width: '100%', height: '100%', ...style }, sandbox: [
+            'allow-same-origin',
+            allowsJavaScript && 'allow-scripts',
+            allowsForms && 'allow-forms',
+        ]
+            .filter(Boolean)
+            .join(' '), referrerPolicy: "no-referrer", onError: () => publish({ status: 'unavailable', reason: 'load-error' }), onLoad: () => {
+            try {
+                const frame = ref.current;
+                const document = frame?.contentDocument;
+                const current = frame?.contentWindow?.location;
+                if (!document ||
+                    !current ||
+                    current.href === 'about:blank' ||
+                    current.origin !== location.origin) {
+                    publish({ status: 'unverified', reason: 'cross-origin-or-denied' });
+                }
+                else
+                    publish({ status: 'loaded', url: current.href, title: document.title });
+            }
+            catch {
+                publish({ status: 'unverified', reason: 'cross-origin-or-denied' });
+            }
+        } }));
+}

package/dist/web/authentication.d.ts

@@ -0,0 +1,75 @@
+export interface WebAuthenticationConfiguration {
+    /** Stable name, unique within this app origin. */
+    id: string;
+    authorizationURL: string;
+    clientID: string;
+    /** Dedicated same-origin callback document outside appURL's scope. Never cache it. */
+    callbackURL: string;
+    /** The app's trailing-slash scope URL. */
+    appURL: string;
+    scopes?: readonly string[];
+    /** Required for OpenID Connect; the server must verify issuer, audience, signature and nonce. */
+    issuer?: string;
+    timeoutMs?: number;
+    /** Optional same-origin POST endpoint implementing the documented bridge protocol. */
+    bridgeURL?: string;
+    /** Establish your session on the server. Never return or message tokens to another window. */
+    exchange: (request: WebAuthenticationExchange) => Promise<void>;
+}
+export interface WebAuthenticationExchange {
+    code: string;
+    codeVerifier: string;
+    callbackURL: string;
+    /** Use this as the server's idempotency key. */
+    transactionID: string;
+    nonce: string;
+    expectedIssuer?: string;
+    signal: AbortSignal;
+}
+export type WebAuthenticationState = {
+    status: 'idle';
+} | {
+    status: 'prepared' | 'pending' | 'completing';
+    expiresAt: number;
+    needsReturn: boolean;
+} | {
+    status: 'succeeded' | 'cancelled' | 'expired';
+} | {
+    status: 'failed' | 'unavailable';
+    reason: string;
+};
+export type WebAuthenticationStartResult = {
+    status: 'dispatched';
+    transport: 'popup' | 'redirect';
+} | {
+    status: 'unavailable';
+    reason: string;
+};
+export type WebAuthenticationCallbackResult = {
+    status: 'completed';
+    returnURL: string;
+} | {
+    status: 'rejected' | 'unavailable';
+    reason: string;
+};
+export interface WebAuthenticationRequest {
+    /** Call synchronously in the user's press handler. A blocked popup may retry as redirect. */
+    start(options?: {
+        transport?: 'popup' | 'redirect';
+    }): WebAuthenticationStartResult;
+}
+export interface WebAuthentication {
+    /** Generate PKCE and durably register the transaction before enabling the sign-in button. */
+    prepare(): Promise<WebAuthenticationRequest>;
+    /** Validate and store the callback on the dedicated callback document. */
+    complete(): Promise<WebAuthenticationCallbackResult>;
+    /** Reconcile durable completion on launch, pageshow, focus and return from suspension. */
+    resume(): Promise<WebAuthenticationState>;
+    cancel(): void;
+    getSnapshot(): WebAuthenticationState;
+    subscribe(listener: () => void): () => void;
+    /** Attach bounded popup monitoring and lifecycle listeners. Returns their cleanup. */
+    connect(): () => void;
+}
+/** Durable authorization-code + PKCE handoff. This does not implement a native authentication session. */
+export declare function defineWebAuthentication(configuration: WebAuthenticationConfiguration): WebAuthentication;