@synopackageland/ui 0.20.3 → 0.20.4

package/dist/interaction/editSession.d.ts

@@ -0,0 +1,49 @@
+import { OutsideResult } from './outside';
+/**
+ * - `committed`: the draft was handed to `onCommit` and edit ended
+ * - `clean`: nothing changed; edit ended without a commit
+ * - `invalid`: `validate` rejected the draft; still editing (the veto)
+ * - `composing`: an IME owns the input; the commit runs when composition ends
+ * - `idle`: there was no edit
+ */
+export type EditCommitResult = 'committed' | 'clean' | 'invalid' | 'composing' | 'idle';
+/** Plain state; `version` increases on every change so a host can bump one shallowRef. */
+export interface EditSessionState<Cell, Value> {
+    readonly editing: boolean;
+    readonly cell: Cell | null;
+    readonly original: Value | undefined;
+    readonly draft: Value | undefined;
+    readonly composing: boolean;
+    readonly dirty: boolean;
+    /** Message from the last rejected commit; cleared by the next draft change. */
+    readonly error: string | null;
+    readonly version: number;
+}
+export interface EditSessionOptions<Cell, Value> {
+    equals?: (a: Value | undefined, b: Value | undefined) => boolean;
+    /** Return a message to veto the commit; the editor stays open. */
+    validate?: (draft: Value | undefined, cell: Cell) => string | null | undefined;
+    /** Apply the value locally, synchronously. Saving it is the caller's job. */
+    onCommit: (cell: Cell, draft: Value | undefined, original: Value | undefined) => void;
+    onCancel?: (cell: Cell, original: Value | undefined) => void;
+    onChange?: (state: EditSessionState<Cell, Value>) => void;
+}
+export interface EditSession<Cell, Value> {
+    readonly state: EditSessionState<Cell, Value>;
+    /** Enter edit synchronously; `draft` defaults to the value (a first typed key passes ''). */
+    start(cell: Cell, value: Value | undefined, draft?: Value | undefined): void;
+    setDraft(draft: Value | undefined): void;
+    /** Feed composition start/end; ending a composition runs a commit that was waiting for it. */
+    setComposing(composing: boolean): void;
+    commit(): EditCommitResult;
+    /** Restore the original and leave edit. False while composing: Escape belongs to the IME. */
+    cancel(): boolean;
+}
+export declare function createEditSession<Cell, Value>(options: EditSessionOptions<Cell, Value>): EditSession<Cell, Value>;
+/**
+ * The §3.5 outside rules for a selectable, editable surface:
+ * - editing: commit (clean edits just close); an invalid draft vetoes the press;
+ *   the selection stays
+ * - selected, not editing: clear the selection
+ */
+export declare function editSessionOutside<Cell, Value>(session: EditSession<Cell, Value>, clearSelection?: () => void): (event: PointerEvent) => OutsideResult;

package/dist/interaction/focus.d.ts

@@ -0,0 +1,28 @@
+/** Dialog containers whose focus and keys belong to whoever opened them. */
+export declare const DIALOG_SELECTOR = "[role=\"dialog\"],[role=\"alertdialog\"],[aria-modal=\"true\"]";
+/**
+ * True when `node` sits in a dialog that does not contain `owner`: a dialog
+ * opened over the surface owns focus and keys, so the surface must not take
+ * them back. A dialog that contains the owner is the owner's own context.
+ */
+export declare function isInForeignDialog(node: Node | null | undefined, owner: Node): boolean;
+/** Same test for an event path, which stays valid after its nodes are removed. */
+export declare function pathInForeignDialog(path: readonly EventTarget[], owners: readonly Node[]): boolean;
+/**
+ * Focuses `element` synchronously, without scrolling, unless a foreign dialog
+ * holds focus. Call it inside the pointerdown or key handler that changed the
+ * selection, so the next key and the first IME symbol land in this element
+ * rather than in whatever held focus a frame earlier.
+ */
+export declare function focusSync(element: HTMLElement | null | undefined, owner?: Node | null): boolean;
+export interface FocusOwner {
+    /** Focus the owner element now; false when it is missing or a foreign dialog keeps focus. */
+    claim(): boolean;
+    /** True when the owner element has focus. */
+    owns(): boolean;
+}
+/**
+ * A single focus owner for a surface (for a grid: the hidden input over the
+ * active cell). `element` is read on each call, so the host may swap nodes.
+ */
+export declare function createFocusOwner(element: () => HTMLElement | null | undefined, surface?: () => Node | null | undefined): FocusOwner;

package/dist/interaction/gesture.d.ts

@@ -0,0 +1,49 @@
+/** Distance a mouse press must travel before it becomes a drag. */
+export declare const DRAG_THRESHOLD_PX = 5;
+export type GestureAxis = 'x' | 'y' | 'both';
+export type GestureCancelReason = 'pointercancel' | 'blur' | 'dispose';
+/** Plain, mutable gesture state; never reactive, read it in the callbacks. */
+export interface PointerGestureState {
+    readonly pointerId: number;
+    readonly pointerType: string;
+    readonly startX: number;
+    readonly startY: number;
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    /** True once the threshold was crossed. */
+    dragging: boolean;
+}
+export interface PointerGestureOptions {
+    threshold?: number;
+    /** Axis the threshold is measured on; `both` uses the larger of the two. */
+    axis?: GestureAxis;
+    /** Capture the pointer on the pressed element (default true). */
+    capture?: boolean;
+    /** Swallow the click that follows a finished drag (default true). */
+    suppressClick?: boolean;
+    onStart?: (state: PointerGestureState, event: PointerEvent) => void;
+    onMove?: (state: PointerGestureState, event: PointerEvent) => void;
+    /** Pointer released. `state.dragging` tells a drag from a press. */
+    onEnd?: (state: PointerGestureState, event: PointerEvent) => void;
+    onCancel?: (state: PointerGestureState, reason: GestureCancelReason) => void;
+}
+export interface PointerGesture {
+    readonly state: PointerGestureState;
+    readonly active: boolean;
+    /** Stop tracking, release capture and listeners, and report `dispose` to `onCancel`. */
+    dispose(): void;
+}
+/**
+ * Tracks one pointer from its pointerdown. Moves are read from the event only
+ * (no layout reads). Listeners are on the window in capture, so tracking goes on
+ * outside the pressed element; pointercancel, window blur and `dispose()`
+ * release capture and every listener.
+ */
+export declare function trackPointerGesture(event: PointerEvent, options?: PointerGestureOptions): PointerGesture;
+/**
+ * Drop index for reordering along one axis: the hovered item's index when the
+ * pointer is in its first half, otherwise the index after it.
+ */
+export declare function dropIndexAt(offset: number, index: number, itemStart: number, itemSize: number): number;

package/dist/interaction/ime.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license MIT
+ * `isPrintableKey` is ported from Teable
+ * (packages/sdk/src/components/grid/utils/hotkey.ts at f8be01fad), with the
+ * ts-key-enum / ts-keycode-enum constants replaced by their numeric values.
+ *
+ * Copyright (c) 2023-2025 Teable, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Window after `compositionend` in which a command key still belongs to the IME.
+ * Safari sends the Enter that picks a candidate as a plain keydown right after
+ * `compositionend`; a person cannot press another Enter this quickly.
+ */
+export declare const COMPOSITION_END_GRACE_MS = 50;
+/** True while the IME owns the key: `isComposing`, or the legacy keyCode 229. */
+export declare function isComposingKey(event: KeyboardEvent): boolean;
+/** First-key test for starting an edit from a selected cell; keyCode 229 starts IME input. */
+export declare function isPrintableKey(event: KeyboardEvent): boolean;
+export interface CompositionGuard {
+    /** True between `compositionstart` and `compositionend`. */
+    readonly composing: boolean;
+    /**
+     * True when Enter, Escape or Tab must be left to the IME: during composition,
+     * or the first command key within the grace window after `compositionend`.
+     */
+    ownsKey(event: KeyboardEvent): boolean;
+    dispose(): void;
+}
+/**
+ * Tracks composition on `target` (an editor, a hidden focus input, or a window)
+ * so command keys are never treated as commit, cancel or move while an IME
+ * owns them. Listeners are capture-phase and removed by `dispose()`.
+ */
+export declare function createCompositionGuard(target: EventTarget, options?: {
+    onStart?: (event: CompositionEvent) => void;
+    onEnd?: (event: CompositionEvent) => void;
+}): CompositionGuard;

package/dist/interaction/index.d.ts

@@ -0,0 +1,6 @@
+export { IGNORE_OUTSIDE_ATTR, IGNORE_OUTSIDE_SELECTOR, outsideLayerCount, registerOutsideLayer, swallowNextClick, type OutsideLayer, type OutsideLayerOptions, type OutsideResult, } from './outside';
+export { COMPOSITION_END_GRACE_MS, createCompositionGuard, isComposingKey, isPrintableKey, type CompositionGuard, } from './ime';
+export { DRAG_THRESHOLD_PX, dropIndexAt, trackPointerGesture, type GestureAxis, type GestureCancelReason, type PointerGesture, type PointerGestureOptions, type PointerGestureState, } from './gesture';
+export { DIALOG_SELECTOR, createFocusOwner, focusSync, isInForeignDialog, pathInForeignDialog, type FocusOwner, } from './focus';
+export { createEditSession, editSessionOutside, type EditCommitResult, type EditSession, type EditSessionOptions, type EditSessionState, } from './editSession';
+export { useEditSession, useOutsideLayer, usePointerGesture } from './vue';

package/dist/interaction/outside.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The single ignore contract. Put it on every portal root that belongs to an
+ * interactive surface (popovers, menus, the grid editor): a press inside it is
+ * never an outside press for any layer, even if the node is removed while the
+ * press is handled.
+ */
+export declare const IGNORE_OUTSIDE_ATTR = "data-ui-ignore-outside";
+export declare const IGNORE_OUTSIDE_SELECTOR = "[data-ui-ignore-outside]";
+/** `'veto'` keeps the layer as it is and blocks the press from reaching its target. */
+export type OutsideResult = void | 'veto';
+export interface OutsideLayerOptions {
+    /** Nodes that belong to this layer: the surface and any portal it opened. Read on every press. */
+    elements: () => Iterable<Node | null | undefined>;
+    /** Runs in window capture, before any handler of the pressed target. */
+    onOutside?: (event: PointerEvent) => OutsideResult;
+    /** Escape for the topmost layer; return true when handled. Never called while an IME owns the key. */
+    onEscape?: (event: KeyboardEvent) => boolean | void;
+}
+export interface OutsideLayer {
+    readonly disposed: boolean;
+    dispose(): void;
+}
+/**
+ * Swallows the next `click` (in capture, before any handler) — used after a
+ * vetoed press or a finished drag so the release does not activate its target.
+ * Expires on the next press, the next key, or after `timeoutMs`.
+ */
+export declare function swallowNextClick(view: Window, timeoutMs?: number): () => void;
+/**
+ * Registers an interactive surface (grid edit, popover, side panel) as the
+ * topmost layer of its window. One capture listener per window serves every
+ * layer and is removed with the last one.
+ *
+ * On pointerdown, layers are visited from the top: the first layer that
+ * contains the press stops the walk; every layer above it gets `onOutside`
+ * once, before the target's own handlers. Escape goes to the topmost layer only.
+ */
+export declare function registerOutsideLayer(view: Window, options: OutsideLayerOptions): OutsideLayer;
+/** Number of live layers in `view`, for tests and diagnostics. */
+export declare function outsideLayerCount(view: Window): number;

package/dist/interaction/vue.d.ts

@@ -0,0 +1,21 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { EditSession, EditSessionOptions } from './editSession';
+import { PointerGesture, PointerGestureOptions } from './gesture';
+import { OutsideLayerOptions } from './outside';
+type Nodes = MaybeRefOrGetter<Node | null | undefined | readonly (Node | null | undefined)[]>;
+/**
+ * Registers `elements` as an outside layer while `active` is true, and
+ * disposes it when `active` turns false or the owning scope (component) ends.
+ */
+export declare function useOutsideLayer(elements: Nodes, active: MaybeRefOrGetter<boolean>, handlers: Omit<OutsideLayerOptions, 'elements'>): import('vue').WatchHandle;
+/** One pointer gesture at a time, disposed (capture and listeners released) with the scope. */
+export declare function usePointerGesture(): {
+    start(event: PointerEvent, options?: PointerGestureOptions): PointerGesture;
+    dispose: () => void;
+};
+/** `createEditSession` with one shallowRef bump per change for templates. */
+export declare function useEditSession<Cell, Value>(options: EditSessionOptions<Cell, Value>): {
+    session: EditSession<Cell, Value>;
+    version: Readonly<Ref<number>>;
+};
+export {};

package/dist/json-ai-prompt.md

@@ -173,7 +173,7 @@ RULES:
 21. Keep state in the spec and use $bindState/$bindItem for editable controls; do not invent JavaScript in props.
 22. Use host-declared actions for side effects. Never encode fetch, timers, filesystem operations, or business logic as UI expressions.
 23. If a domain view needs custom rendering or behavior (for example a treemap, terminal, rich download row, NAS path picker), use a host extension component instead of forcing it into generic components.
-24. AppShell adapts to its actual DSM window width: phone (<=600px), desktop window (601–1199px), and wide web/Portal (>=1200px). Never assume browser viewport width.
+24. AppShell adapts to its actual container width: phone (<=640px), desktop window (641px and wider), and, only with wideLayout "web", the full-page web layout from 960px (its sidebar starts as a 48px rail below 1200px). Never assume browser viewport width.
 25. For a phone-unfriendly custom view, use ResponsiveView slots: mobile alternative and default full view. Keep essential actions accessible on mobile.
 26. Use low-level Stack/Text only when a semantic component does not already express the layout.