@skdx/react 0.26.0

package/dist/editable/EditableEditTrigger.d.cts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { EditableEditTriggerProps } from './types.cjs';
+/**
+ * A button that opens an edit from *outside* the preview — a pencil icon in a
+ * table row, an "Edit" item in a toolbar. Renders `nothing` while editing.
+ * Disabled whenever the root is `disabled` or `readOnly`, since neither can be
+ * edited.
+ *
+ * It is the discoverable counterpart to `activationMode`: `'dblclick'` avoids
+ * accidental edits but is invisible, so pair the two when the surface is
+ * read-mostly. Focus still lands on the input when the edit opens, and returns
+ * to the *preview* — not to this trigger — when it closes, because the preview
+ * is where the text the user was just working on now lives.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" activationMode="dblclick">
+ *   <EditablePreview />
+ *   <EditableEditTrigger aria-label="Edit title">✎</EditableEditTrigger>
+ *   <EditableInput aria-label="Title" />
+ * </Editable>
+ * ```
+ */
+export declare const EditableEditTrigger: React.ForwardRefExoticComponent<Omit<EditableEditTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/editable/EditableEditTrigger.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { EditableEditTriggerProps } from './types.js';
+/**
+ * A button that opens an edit from *outside* the preview — a pencil icon in a
+ * table row, an "Edit" item in a toolbar. Renders `nothing` while editing.
+ * Disabled whenever the root is `disabled` or `readOnly`, since neither can be
+ * edited.
+ *
+ * It is the discoverable counterpart to `activationMode`: `'dblclick'` avoids
+ * accidental edits but is invisible, so pair the two when the surface is
+ * read-mostly. Focus still lands on the input when the edit opens, and returns
+ * to the *preview* — not to this trigger — when it closes, because the preview
+ * is where the text the user was just working on now lives.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" activationMode="dblclick">
+ *   <EditablePreview />
+ *   <EditableEditTrigger aria-label="Edit title">✎</EditableEditTrigger>
+ *   <EditableInput aria-label="Title" />
+ * </Editable>
+ * ```
+ */
+export declare const EditableEditTrigger: React.ForwardRefExoticComponent<Omit<EditableEditTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/editable/EditableInput.d.cts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { EditableInputProps } from './types.cjs';
+/**
+ * The single-line editor for an {@link Editable}. Renders `nothing` outside
+ * edit mode, and a controlled `<input type="text">` inside it, taking its
+ * value, `placeholder`, `disabled`, `readOnly`, `required` and `maxLength`
+ * from the root — so the only prop you normally pass is an accessible name.
+ *
+ * Key handling: Escape always cancels and restores the pre-edit text; Enter
+ * submits when `submitMode` is `'enter'` or `'both'`; blur submits when it is
+ * `'blur'` or `'both'`. For multi-line text where Enter has to mean *newline*,
+ * use `EditableTextarea` instead.
+ *
+ * The root focuses this element and selects (or places the caret at the end
+ * of) its content when edit mode opens; you do not have to focus it yourself.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" submitMode="enter">
+ *   <EditablePreview />
+ *   <EditableInput aria-label="Document title" />
+ * </Editable>
+ * ```
+ */
+export declare const EditableInput: React.ForwardRefExoticComponent<Omit<EditableInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/editable/EditableInput.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { EditableInputProps } from './types.js';
+/**
+ * The single-line editor for an {@link Editable}. Renders `nothing` outside
+ * edit mode, and a controlled `<input type="text">` inside it, taking its
+ * value, `placeholder`, `disabled`, `readOnly`, `required` and `maxLength`
+ * from the root — so the only prop you normally pass is an accessible name.
+ *
+ * Key handling: Escape always cancels and restores the pre-edit text; Enter
+ * submits when `submitMode` is `'enter'` or `'both'`; blur submits when it is
+ * `'blur'` or `'both'`. For multi-line text where Enter has to mean *newline*,
+ * use `EditableTextarea` instead.
+ *
+ * The root focuses this element and selects (or places the caret at the end
+ * of) its content when edit mode opens; you do not have to focus it yourself.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" submitMode="enter">
+ *   <EditablePreview />
+ *   <EditableInput aria-label="Document title" />
+ * </Editable>
+ * ```
+ */
+export declare const EditableInput: React.ForwardRefExoticComponent<Omit<EditableInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/editable/EditablePreview.d.cts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { EditablePreviewProps } from './types.cjs';
+/**
+ * The read-mode half of an {@link Editable}: the text as it currently stands,
+ * and the thing you interact with to start editing it. Renders `nothing` while
+ * editing — the input has taken its place — and a `role="button"` `<span>`
+ * otherwise, with `data-state="preview"`, `data-empty`, `data-disabled` and
+ * `data-readonly`.
+ *
+ * With no children it renders the value, falling back to the root's
+ * `placeholder` when empty. Pass children to render the value yourself (a
+ * heading, a truncated cell); they replace the text entirely.
+ *
+ * It is a tab stop unless `disabled`, and Enter or Space opens the editor
+ * whatever `activationMode` is set to — a click-to-edit affordance that only
+ * responds to a mouse is not an affordance for half your users. This is also
+ * the element focus comes back to when the edit ends.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" placeholder="Add a title">
+ *   <EditablePreview />
+ *   <EditableInput aria-label="Title" />
+ * </Editable>
+ * ```
+ */
+export declare const EditablePreview: React.ForwardRefExoticComponent<Omit<EditablePreviewProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/editable/EditablePreview.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { EditablePreviewProps } from './types.js';
+/**
+ * The read-mode half of an {@link Editable}: the text as it currently stands,
+ * and the thing you interact with to start editing it. Renders `nothing` while
+ * editing — the input has taken its place — and a `role="button"` `<span>`
+ * otherwise, with `data-state="preview"`, `data-empty`, `data-disabled` and
+ * `data-readonly`.
+ *
+ * With no children it renders the value, falling back to the root's
+ * `placeholder` when empty. Pass children to render the value yourself (a
+ * heading, a truncated cell); they replace the text entirely.
+ *
+ * It is a tab stop unless `disabled`, and Enter or Space opens the editor
+ * whatever `activationMode` is set to — a click-to-edit affordance that only
+ * responds to a mouse is not an affordance for half your users. This is also
+ * the element focus comes back to when the edit ends.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" placeholder="Add a title">
+ *   <EditablePreview />
+ *   <EditableInput aria-label="Title" />
+ * </Editable>
+ * ```
+ */
+export declare const EditablePreview: React.ForwardRefExoticComponent<Omit<EditablePreviewProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/editable/EditableSubmitTrigger.d.cts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { EditableSubmitTriggerProps } from './types.cjs';
+/**
+ * A button that commits the current draft of an {@link Editable}. Renders
+ * `nothing` outside edit mode. Required when `submitMode="none"`, optional
+ * otherwise — a visible "Save" next to Enter-to-submit is the discoverable
+ * version of the same action.
+ *
+ * It calls `preventDefault()` on mouse-down so that pressing it does not blur
+ * the input first: under `submitMode="both"` that blur would submit and
+ * unmount this button, so the click would land on nothing.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" submitMode="none">
+ *   <EditablePreview />
+ *   <EditableInput aria-label="Title" />
+ *   <EditableSubmitTrigger>Save</EditableSubmitTrigger>
+ *   <EditableCancelTrigger>Cancel</EditableCancelTrigger>
+ * </Editable>
+ * ```
+ */
+export declare const EditableSubmitTrigger: React.ForwardRefExoticComponent<Omit<EditableSubmitTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/editable/EditableSubmitTrigger.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { EditableSubmitTriggerProps } from './types.js';
+/**
+ * A button that commits the current draft of an {@link Editable}. Renders
+ * `nothing` outside edit mode. Required when `submitMode="none"`, optional
+ * otherwise — a visible "Save" next to Enter-to-submit is the discoverable
+ * version of the same action.
+ *
+ * It calls `preventDefault()` on mouse-down so that pressing it does not blur
+ * the input first: under `submitMode="both"` that blur would submit and
+ * unmount this button, so the click would land on nothing.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="Untitled" submitMode="none">
+ *   <EditablePreview />
+ *   <EditableInput aria-label="Title" />
+ *   <EditableSubmitTrigger>Save</EditableSubmitTrigger>
+ *   <EditableCancelTrigger>Cancel</EditableCancelTrigger>
+ * </Editable>
+ * ```
+ */
+export declare const EditableSubmitTrigger: React.ForwardRefExoticComponent<Omit<EditableSubmitTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/editable/EditableTextarea.d.cts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { EditableTextareaProps } from './types.cjs';
+/**
+ * The multi-line editor for an {@link Editable} — a drop-in alternative to
+ * `EditableInput`, never rendered alongside it. Renders `nothing` outside edit
+ * mode, and a controlled `<textarea>` inside it, taking value, `placeholder`,
+ * `disabled`, `readOnly`, `required` and `maxLength` from the root.
+ *
+ * The one behavioural difference is Enter, and it matters: in a multi-line
+ * field Enter has to insert a newline, so **Cmd/Ctrl+Enter** submits instead
+ * (still gated on `submitMode` including `'enter'`). A plain Enter is left
+ * entirely alone. Escape still cancels, and blur still submits under
+ * `submitMode` `'blur'`/`'both'`.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="" placeholder="Add a note" submitMode="enter">
+ *   <EditablePreview />
+ *   <EditableTextarea aria-label="Note" rows={4} />
+ * </Editable>
+ * ```
+ */
+export declare const EditableTextarea: React.ForwardRefExoticComponent<Omit<EditableTextareaProps, "ref"> & React.RefAttributes<HTMLTextAreaElement>>;

package/dist/editable/EditableTextarea.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { EditableTextareaProps } from './types.js';
+/**
+ * The multi-line editor for an {@link Editable} — a drop-in alternative to
+ * `EditableInput`, never rendered alongside it. Renders `nothing` outside edit
+ * mode, and a controlled `<textarea>` inside it, taking value, `placeholder`,
+ * `disabled`, `readOnly`, `required` and `maxLength` from the root.
+ *
+ * The one behavioural difference is Enter, and it matters: in a multi-line
+ * field Enter has to insert a newline, so **Cmd/Ctrl+Enter** submits instead
+ * (still gated on `submitMode` including `'enter'`). A plain Enter is left
+ * entirely alone. Escape still cancels, and blur still submits under
+ * `submitMode` `'blur'`/`'both'`.
+ *
+ * @example
+ * ```tsx
+ * <Editable defaultValue="" placeholder="Add a note" submitMode="enter">
+ *   <EditablePreview />
+ *   <EditableTextarea aria-label="Note" rows={4} />
+ * </Editable>
+ * ```
+ */
+export declare const EditableTextarea: React.ForwardRefExoticComponent<Omit<EditableTextareaProps, "ref"> & React.RefAttributes<HTMLTextAreaElement>>;

package/dist/editable/index.d.cts

@@ -0,0 +1,8 @@
+export * from './Editable.cjs';
+export { EditableCancelTrigger } from './EditableCancelTrigger.cjs';
+export { EditableEditTrigger } from './EditableEditTrigger.cjs';
+export { EditableInput } from './EditableInput.cjs';
+export { EditablePreview } from './EditablePreview.cjs';
+export { EditableSubmitTrigger } from './EditableSubmitTrigger.cjs';
+export { EditableTextarea } from './EditableTextarea.cjs';
+export type { EditableActivationMode, EditableCancelTriggerProps, EditableEditTriggerProps, EditableInputProps, EditablePreviewProps, EditableProps, EditableSubmitMode, EditableSubmitTriggerProps, EditableTextareaProps, } from './types.cjs';

package/dist/editable/index.d.ts

@@ -0,0 +1,8 @@
+export * from './Editable.js';
+export { EditableCancelTrigger } from './EditableCancelTrigger.js';
+export { EditableEditTrigger } from './EditableEditTrigger.js';
+export { EditableInput } from './EditableInput.js';
+export { EditablePreview } from './EditablePreview.js';
+export { EditableSubmitTrigger } from './EditableSubmitTrigger.js';
+export { EditableTextarea } from './EditableTextarea.js';
+export type { EditableActivationMode, EditableCancelTriggerProps, EditableEditTriggerProps, EditableInputProps, EditablePreviewProps, EditableProps, EditableSubmitMode, EditableSubmitTriggerProps, EditableTextareaProps, } from './types.js';

package/dist/editable/types.d.cts

@@ -0,0 +1,151 @@
+import type * as React from 'react';
+import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+/** The element `EditableInput` or `EditableTextarea` renders — whichever one the consumer mounted. */
+export type EditableInputElement = HTMLInputElement | HTMLTextAreaElement;
+/** How interacting with `EditablePreview` enters edit mode. Keyboard activation (Enter/Space) always works, in every mode. */
+export type EditableActivationMode = 'click' | 'dblclick' | 'focus';
+/** Which gestures commit the draft. `'none'` leaves committing entirely to `EditableSubmitTrigger`. */
+export type EditableSubmitMode = 'blur' | 'enter' | 'both' | 'none';
+/** @internal Shared state distributed from {@link Editable} to its parts via context. Not part of the public API. */
+export interface EditableContextValue {
+    value: string;
+    editing: boolean;
+    placeholder: string | undefined;
+    disabled: boolean;
+    readOnly: boolean;
+    required: boolean;
+    maxLength: number | undefined;
+    activationMode: EditableActivationMode;
+    submitMode: EditableSubmitMode;
+    /** Set by whichever of `EditableInput`/`EditableTextarea` is mounted, so the root can focus it on entering edit mode. */
+    inputRef: React.RefObject<EditableInputElement | null>;
+    /** Set by `EditablePreview`, so the root can return focus to it on leaving edit mode. */
+    previewRef: React.RefObject<HTMLSpanElement | null>;
+    /**
+     * True only for the instant the root is programmatically returning focus to
+     * the preview. `activationMode="focus"` reads it to avoid re-entering edit
+     * mode on the focus it just caused — otherwise submitting would loop forever.
+     */
+    returningFocusRef: React.RefObject<boolean>;
+    setValue: (value: string) => void;
+    activate: () => void;
+    submit: () => void;
+    cancel: () => void;
+}
+/** Props for the {@link Editable} root. */
+export interface EditableProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Current text, for controlled usage. Pair with `onValueChange`. Note this
+     * tracks the *live* draft while editing, not only committed text — use
+     * `onValueCommit` if you only care about the submitted result.
+     * @default undefined — uncontrolled, tracks its own value internally.
+     */
+    value?: string;
+    /**
+     * Initial text, for uncontrolled usage, seeding the first render.
+     * @default undefined — starts empty, so the preview shows `placeholder` and the root carries `data-empty`.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new text on every keystroke while editing, and again with
+     * the restored text when an edit is cancelled or rejected.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * Fires once with the final text when an edit is *successfully* submitted.
+     * Never fires for Escape-cancel, nor for a `required` field submitted empty —
+     * both of those restore the pre-edit text instead. This is the callback to
+     * hang a network write off; `onValueChange` would fire it per keystroke.
+     * @default undefined — no-op if omitted.
+     */
+    onValueCommit?: (value: string) => void;
+    /**
+     * Whether the input is showing instead of the preview, for controlled usage.
+     * Pair with `onEditChange`.
+     * @default undefined — uncontrolled, tracks its own edit state internally.
+     */
+    editing?: boolean;
+    /**
+     * Whether to start in edit mode, for uncontrolled usage. Starting `true`
+     * focuses the input on mount, so use it only when the edit is the reason the
+     * surface appeared (a freshly added row), never on a page the user just landed on.
+     * @default false — starts showing the preview.
+     */
+    defaultEditing?: boolean;
+    /**
+     * Fires with the new edit state whenever it flips, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onEditChange?: (editing: boolean) => void;
+    /**
+     * Text rendered by `EditablePreview` when the value is empty, and set as the
+     * input's `placeholder`. It doubles as the preview's accessible name while
+     * empty, so an editable with no placeholder and no value renders a button
+     * with no name — always supply one, or an `aria-label` on the preview.
+     * @default undefined — an empty value renders an empty preview.
+     */
+    placeholder?: string;
+    /**
+     * Blocks editing entirely and takes the preview out of the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Shows the value but blocks entering edit mode. The preview stays focusable
+     * (unlike `disabled`), so the text is still reachable by keyboard.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Rejects a submit that would leave the value blank: the pre-edit text is
+     * restored, `onValueCommit` does not fire, and edit mode closes. Whitespace
+     * counts as blank.
+     * @default false — an empty submit is committed like any other.
+     */
+    required?: boolean;
+    /**
+     * Maximum number of characters the input accepts, forwarded to the native
+     * `maxLength` attribute.
+     * @default undefined — no limit.
+     */
+    maxLength?: number;
+    /**
+     * Which pointer gesture on `EditablePreview` enters edit mode. `'focus'`
+     * makes the field editable as soon as it is tabbed to — convenient in a form,
+     * hostile in a read-mostly page, where `'dblclick'` avoids editing on a stray click.
+     * @default 'click' — a single click on the preview starts editing.
+     */
+    activationMode?: EditableActivationMode;
+    /**
+     * Which gestures commit the draft: `'enter'` (Enter key), `'blur'` (focus
+     * leaves the input), `'both'`, or `'none'` — which leaves committing to
+     * `EditableSubmitTrigger` alone. Escape always cancels regardless.
+     * @default 'both' — Enter and blur each submit.
+     */
+    submitMode?: EditableSubmitMode;
+    /**
+     * Select the whole value when edit mode opens, so typing replaces it. With
+     * `false` the caret is placed at the end instead, so typing appends.
+     * @default true — entering edit mode selects everything.
+     */
+    selectOnFocus?: boolean;
+}
+/** Props for {@link EditablePreview}, the read-mode text that starts an edit. Renders nothing while editing. */
+export interface EditablePreviewProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link EditableInput}, the single-line editor. Value, placeholder and constraints come from {@link Editable}'s context. */
+export interface EditableInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link EditableTextarea}, the multi-line editor. Value, placeholder and constraints come from {@link Editable}'s context. */
+export interface EditableTextareaProps extends Omit<PrimitivePropsWithRef<'textarea'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link EditableSubmitTrigger}, the button that commits the draft. Renders nothing outside edit mode. */
+export interface EditableSubmitTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link EditableCancelTrigger}, the button that discards the draft. Renders nothing outside edit mode. */
+export interface EditableCancelTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link EditableEditTrigger}, the button that opens an edit from outside the preview. Renders nothing while editing. */
+export interface EditableEditTriggerProps extends PrimitivePropsWithRef<'button'> {
+}

package/dist/editable/types.d.ts

@@ -0,0 +1,151 @@
+import type * as React from 'react';
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+/** The element `EditableInput` or `EditableTextarea` renders — whichever one the consumer mounted. */
+export type EditableInputElement = HTMLInputElement | HTMLTextAreaElement;
+/** How interacting with `EditablePreview` enters edit mode. Keyboard activation (Enter/Space) always works, in every mode. */
+export type EditableActivationMode = 'click' | 'dblclick' | 'focus';
+/** Which gestures commit the draft. `'none'` leaves committing entirely to `EditableSubmitTrigger`. */
+export type EditableSubmitMode = 'blur' | 'enter' | 'both' | 'none';
+/** @internal Shared state distributed from {@link Editable} to its parts via context. Not part of the public API. */
+export interface EditableContextValue {
+    value: string;
+    editing: boolean;
+    placeholder: string | undefined;
+    disabled: boolean;
+    readOnly: boolean;
+    required: boolean;
+    maxLength: number | undefined;
+    activationMode: EditableActivationMode;
+    submitMode: EditableSubmitMode;
+    /** Set by whichever of `EditableInput`/`EditableTextarea` is mounted, so the root can focus it on entering edit mode. */
+    inputRef: React.RefObject<EditableInputElement | null>;
+    /** Set by `EditablePreview`, so the root can return focus to it on leaving edit mode. */
+    previewRef: React.RefObject<HTMLSpanElement | null>;
+    /**
+     * True only for the instant the root is programmatically returning focus to
+     * the preview. `activationMode="focus"` reads it to avoid re-entering edit
+     * mode on the focus it just caused — otherwise submitting would loop forever.
+     */
+    returningFocusRef: React.RefObject<boolean>;
+    setValue: (value: string) => void;
+    activate: () => void;
+    submit: () => void;
+    cancel: () => void;
+}
+/** Props for the {@link Editable} root. */
+export interface EditableProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange'> {
+    /**
+     * Current text, for controlled usage. Pair with `onValueChange`. Note this
+     * tracks the *live* draft while editing, not only committed text — use
+     * `onValueCommit` if you only care about the submitted result.
+     * @default undefined — uncontrolled, tracks its own value internally.
+     */
+    value?: string;
+    /**
+     * Initial text, for uncontrolled usage, seeding the first render.
+     * @default undefined — starts empty, so the preview shows `placeholder` and the root carries `data-empty`.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new text on every keystroke while editing, and again with
+     * the restored text when an edit is cancelled or rejected.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * Fires once with the final text when an edit is *successfully* submitted.
+     * Never fires for Escape-cancel, nor for a `required` field submitted empty —
+     * both of those restore the pre-edit text instead. This is the callback to
+     * hang a network write off; `onValueChange` would fire it per keystroke.
+     * @default undefined — no-op if omitted.
+     */
+    onValueCommit?: (value: string) => void;
+    /**
+     * Whether the input is showing instead of the preview, for controlled usage.
+     * Pair with `onEditChange`.
+     * @default undefined — uncontrolled, tracks its own edit state internally.
+     */
+    editing?: boolean;
+    /**
+     * Whether to start in edit mode, for uncontrolled usage. Starting `true`
+     * focuses the input on mount, so use it only when the edit is the reason the
+     * surface appeared (a freshly added row), never on a page the user just landed on.
+     * @default false — starts showing the preview.
+     */
+    defaultEditing?: boolean;
+    /**
+     * Fires with the new edit state whenever it flips, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onEditChange?: (editing: boolean) => void;
+    /**
+     * Text rendered by `EditablePreview` when the value is empty, and set as the
+     * input's `placeholder`. It doubles as the preview's accessible name while
+     * empty, so an editable with no placeholder and no value renders a button
+     * with no name — always supply one, or an `aria-label` on the preview.
+     * @default undefined — an empty value renders an empty preview.
+     */
+    placeholder?: string;
+    /**
+     * Blocks editing entirely and takes the preview out of the tab order.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Shows the value but blocks entering edit mode. The preview stays focusable
+     * (unlike `disabled`), so the text is still reachable by keyboard.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Rejects a submit that would leave the value blank: the pre-edit text is
+     * restored, `onValueCommit` does not fire, and edit mode closes. Whitespace
+     * counts as blank.
+     * @default false — an empty submit is committed like any other.
+     */
+    required?: boolean;
+    /**
+     * Maximum number of characters the input accepts, forwarded to the native
+     * `maxLength` attribute.
+     * @default undefined — no limit.
+     */
+    maxLength?: number;
+    /**
+     * Which pointer gesture on `EditablePreview` enters edit mode. `'focus'`
+     * makes the field editable as soon as it is tabbed to — convenient in a form,
+     * hostile in a read-mostly page, where `'dblclick'` avoids editing on a stray click.
+     * @default 'click' — a single click on the preview starts editing.
+     */
+    activationMode?: EditableActivationMode;
+    /**
+     * Which gestures commit the draft: `'enter'` (Enter key), `'blur'` (focus
+     * leaves the input), `'both'`, or `'none'` — which leaves committing to
+     * `EditableSubmitTrigger` alone. Escape always cancels regardless.
+     * @default 'both' — Enter and blur each submit.
+     */
+    submitMode?: EditableSubmitMode;
+    /**
+     * Select the whole value when edit mode opens, so typing replaces it. With
+     * `false` the caret is placed at the end instead, so typing appends.
+     * @default true — entering edit mode selects everything.
+     */
+    selectOnFocus?: boolean;
+}
+/** Props for {@link EditablePreview}, the read-mode text that starts an edit. Renders nothing while editing. */
+export interface EditablePreviewProps extends PrimitivePropsWithRef<'span'> {
+}
+/** Props for {@link EditableInput}, the single-line editor. Value, placeholder and constraints come from {@link Editable}'s context. */
+export interface EditableInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link EditableTextarea}, the multi-line editor. Value, placeholder and constraints come from {@link Editable}'s context. */
+export interface EditableTextareaProps extends Omit<PrimitivePropsWithRef<'textarea'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link EditableSubmitTrigger}, the button that commits the draft. Renders nothing outside edit mode. */
+export interface EditableSubmitTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link EditableCancelTrigger}, the button that discards the draft. Renders nothing outside edit mode. */
+export interface EditableCancelTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link EditableEditTrigger}, the button that opens an edit from outside the preview. Renders nothing while editing. */
+export interface EditableEditTriggerProps extends PrimitivePropsWithRef<'button'> {
+}

package/dist/field/Field.cjs

@@ -0,0 +1 @@
+"use strict";var Ee=Object.create;var b=Object.defineProperty;var Fe=Object.getOwnPropertyDescriptor;var be=Object.getOwnPropertyNames;var Te=Object.getPrototypeOf,ye=Object.prototype.hasOwnProperty;var Re=(r,e)=>{for(var t in e)b(r,t,{get:e[t],enumerable:!0})},K=(r,e,t,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of be(e))!ye.call(r,i)&&i!==t&&b(r,i,{get:()=>e[i],enumerable:!(o=Fe(e,i))||o.enumerable});return r};var f=(r,e,t)=>(t=r!=null?Ee(Te(r)):{},K(e||!r||!r.__esModule?b(t,"default",{value:r,enumerable:!0}):t,r)),Ie=r=>K(b({},"__esModule",{value:!0}),r);var Pe={};Re(Pe,{CHARACTER_COUNT_ANNOUNCE_DELAY_MS:()=>J,FIELD_CHARACTER_COUNT_ATTRIBUTE:()=>I,FIELD_CONTROL_ATTRIBUTE:()=>D,FIELD_CONTROL_SELECTOR:()=>N,FIELD_VALIDITY_CHANGE_EVENT:()=>S,Field:()=>H,FieldCharacterCount:()=>q,FieldDescription:()=>j,FieldError:()=>Y,FieldLabel:()=>G,Fieldset:()=>w,NATIVE_INVALID_FALLBACK_MESSAGE:()=>O,characterCountMessage:()=>g,characterCountVisible:()=>C,collectFieldErrors:()=>X,errorSummaryScope:()=>Q,findFieldControl:()=>L,focusFieldTarget:()=>Z});module.exports=Ie(Pe);var a=f(require("react"),1),V=require("../utils/composeRefs.cjs"),ee=require("../utils/createContext.cjs"),te=require("../utils/liveAnnouncer.cjs"),re=require("../utils/part.cjs"),k=require("../utils/primitive.cjs"),oe=require("../utils/useCallbackRef.cjs");var S="validity-change",y="data-skdx-field",x="data-skdx-field-name",_="data-skdx-field-message",P="data-skdx-field-description",R="data-skdx-field-error",I="data-skdx-field-character-count",J=1e3;function g(r){let e=Math.abs(r),t=e===1?"character":"characters";return r<0?`You have ${e} ${t} too many`:`You have ${e} ${t} remaining`}function C(r,e,t=0){return t<=0?!0:r>=e*t/100}var O="This field is invalid.",D="data-skdx-field-control",N=[`[${D}]`,'input:not([type="hidden"])',"select","textarea",'[role="textbox"]','[role="searchbox"]','[role="combobox"]','[role="listbox"]','[role="radiogroup"]','[role="group"]','[role="slider"]','[role="spinbutton"]','[role="checkbox"]','[role="radio"]','[role="switch"]'].join(", "),Le=new Set(["radiogroup","group"]),Ae=['input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])","button:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function z(r){return r==null?[]:(Array.isArray(r)?r:[r]).filter(t=>typeof t=="string"&&t.trim()!=="")}function L(r){for(let e of Array.from(r.querySelectorAll(N)))if(e.getAttribute("aria-hidden")!=="true"&&e.closest(`[${y}]`)===r)return e;return null}function M(r,e){for(let t of Array.from(r.querySelectorAll(e)))if(t.closest(`[${y}]`)===r)return t;return null}function xe(r){if(!r)return;let e=r;return e.type==="checkbox"||e.type==="radio"?e.checked:"value"in r?e.value:r.querySelector('input[aria-hidden="true"]')?.value}function v(r){return r==null||r===!1||r===""?!1:!(Array.isArray(r)&&r.length===0)}function p(r,e,t){t?r.setAttribute(e,""):r.removeAttribute(e)}function _e(r,...e){let t=r.split(/\s+/).filter(Boolean);for(let o of e)o&&!t.includes(o)&&t.push(o);return t.join(" ")}function Q(r){return r.closest("form, skdx-form")??r.parentElement??r}function X(r){return Array.from(r.querySelectorAll(`[${y}][data-invalid]`)).flatMap(t=>{let o=L(t),n=M(t,`[${R}]`)?.textContent?.trim()||t.getAttribute(_)||t.getAttribute(x)||"";return!o?.id||!n?[]:[{id:o.id,message:n}]})}function Z(r,e=document){let t=e.getElementById(r);if(!t)return;let o=t.getAttribute("role"),n=(t.tagName==="FIELDSET"||o!==null&&Le.has(o)?t.querySelector(Ae):null)??t;n.focus(),n.scrollIntoView?.({block:"center"})}var T=class{constructor(e){this.options=e;this.props={};this.root=null;this.form=null;this.control=null;this.baseDescribedBy="";this.runToken=0;this.pending=!1;this.injected=[];this.custom=[];this.characterCount=null;this.handleInput=()=>{let e=this.isOverLimit(this.snapshot.count),t=this.readCount();this.update({dirty:!0,filled:v(this.resolveValue()),count:t,errors:this.composeErrors(t)}),this.scheduleCountAnnouncement(t,e),(this.props.mode==="change"||this.snapshot.errors.length>0)&&this.runValidation()};this.handleFocusOut=()=>{let e=this.readCount();this.update({touched:!0,filled:v(this.resolveValue()),count:e,errors:this.composeErrors(e)}),((this.props.mode??"blur")==="blur"||this.snapshot.errors.length>0)&&this.runValidation()};this.handleSubmit=e=>{if(e.target!==this.form)return;this.markTouched();let t=this.runValidation({silent:!0});if(W(t)){e.preventDefault();return}(t.length>0||this.pending)&&e.preventDefault()};this.snapshot={controlId:e.controlId,errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0}}get state(){return this.snapshot}setProps(e){let t=this.props.value;this.props=e;let o=z(e.errors??null),i=!Me(this.injected,o);i&&(this.injected=o);let n=e.value!==t;if(!i&&!n)return;let s=this.readCount();this.update({count:s,filled:v(this.resolveValue()),errors:this.composeErrors(s)})}setCharacterCount(e){if((this.characterCount?.maxLength??null)===(e?.maxLength??null)&&(this.characterCount?.threshold??0)===(e?.threshold??0))return;this.characterCount=e;let o=this.readCount();this.update({count:o,errors:this.composeErrors(o)})}readCount(){let e=this.resolveValue();return typeof e=="string"?e.length:0}countMessage(e){return(this.props.getCharacterCountMessage??g)(e)}isOverLimit(e){return this.characterCount!==null&&e>this.characterCount.maxLength}composeErrors(e=this.snapshot.count){let t=[...this.injected,...this.custom];return this.characterCount&&this.isOverLimit(e)&&t.push(this.countMessage(this.characterCount.maxLength-e)),t}scheduleCountAnnouncement(e,t){let o=this.characterCount;if(!o)return;if(clearTimeout(this.announceTimer),this.isOverLimit(e)){t||this.options.announce(this.countMessage(o.maxLength-e),"assertive");return}if(!C(e,o.maxLength,o.threshold))return;let i=o.maxLength-e;this.announceTimer=setTimeout(()=>{this.options.announce(this.countMessage(i),"polite")},1e3)}connect(e){this.root=e,e.setAttribute(y,""),e.addEventListener("input",this.handleInput,!0),e.addEventListener("change",this.handleInput,!0),e.addEventListener("focusout",this.handleFocusOut,!0),this.form=e.closest("form"),this.form&&e.ownerDocument.addEventListener("submit",this.handleSubmit,!0),this.sync();let t=this.readCount();this.update({filled:v(this.resolveValue()),count:t,errors:this.composeErrors(t)})}disconnect(){clearTimeout(this.announceTimer);let e=this.root;e&&(e.removeEventListener("input",this.handleInput,!0),e.removeEventListener("change",this.handleInput,!0),e.removeEventListener("focusout",this.handleFocusOut,!0),this.form&&e.ownerDocument.removeEventListener("submit",this.handleSubmit,!0),this.root=null,this.form=null,this.control=null)}sync(){let e=this.root;if(!e)return;let t=L(e);t!==this.control&&(this.control=t,this.baseDescribedBy=t?.getAttribute("aria-describedby")??"");let{name:o}=this.props;o?e.setAttribute(x,o):e.removeAttribute(x);let i=this.snapshot.errors.join(" ");if(i?e.setAttribute(_,i):e.removeAttribute(_),this.applyStateAttributes(e),!t)return;t.id||(t.id=this.options.controlId),t.id!==this.snapshot.controlId&&(this.snapshot={...this.snapshot,controlId:t.id},this.options.onSnapshotChange(this.snapshot));let n=M(e,`[${P}]`)!==null,s=M(e,`[${R}]`)!==null,l=_e(this.baseDescribedBy,n?this.options.descriptionId:void 0,s?this.options.errorId:void 0);l?t.setAttribute("aria-describedby",l):t.removeAttribute("aria-describedby"),this.snapshot.errors.length>0?t.setAttribute("aria-invalid","true"):t.removeAttribute("aria-invalid");let d=e.ownerDocument.getElementById(this.options.labelId)!==null;this.options.grouped&&d?t.setAttribute("aria-labelledby",this.options.labelId):t.getAttribute("aria-labelledby")===this.options.labelId&&t.removeAttribute("aria-labelledby"),this.applyStateAttributes(t)}validate(){return Promise.resolve(this.runValidation()).then(e=>e.length===0)}markTouched(){this.snapshot.touched||this.update({touched:!0})}applyStateAttributes(e){let{errors:t,touched:o,dirty:i,filled:n,count:s}=this.snapshot;p(e,"data-invalid",t.length>0),p(e,"data-valid",t.length===0),p(e,"data-touched",o),p(e,"data-dirty",i),p(e,"data-filled",n),p(e,"data-over-limit",this.isOverLimit(s))}resolveValue(){return this.props.value!==void 0?this.props.value:xe(this.control)}nativeMessage(){let e=this.control;return!e?.validity||e.validity.valid?null:e.validationMessage||this.props.invalidMessage||O}runValidation(e={}){let t=++this.runToken,o=this.props.validate?.(this.resolveValue());return W(o)?(this.pending=!0,Promise.resolve(o).then(i=>t!==this.runToken?this.snapshot.errors:(this.pending=!1,this.commit(i,e)))):this.commit(o,e)}commit(e,t){if(this.custom=z(e),this.custom.length===0&&this.injected.length===0){let l=this.nativeMessage();l&&(this.custom=[l])}let o=this.readCount(),i=this.composeErrors(o),n=this.snapshot.errors.length===0;this.update({errors:i,count:o,filled:v(this.resolveValue())});let s=i[0];return s&&n&&!t.silent&&this.options.announce(s,"assertive"),i}update(e){let t={...this.snapshot,...e,valid:!0};t.valid=t.errors.length===0,!Se(this.snapshot,t)&&(this.snapshot=t,this.sync(),this.options.onSnapshotChange(t),this.root?.dispatchEvent(new CustomEvent(S,{bubbles:!0,composed:!0,detail:{valid:t.valid,errors:t.errors,touched:t.touched,dirty:t.dirty,filled:t.filled,count:t.count}})))}};function W(r){return typeof r?.then=="function"}function Me(r,e){return r.length===e.length&&r.every((t,o)=>t===e[o])}function Se(r,e){return r.controlId===e.controlId&&r.valid===e.valid&&r.touched===e.touched&&r.dirty===e.dirty&&r.filled===e.filled&&r.count===e.count&&r.errors.length===e.errors.length&&r.errors.every((t,o)=>t===e.errors[o])}var E=require("react/jsx-runtime"),[ie,c]=(0,ee.createSafeContext)("Field");function ne(r,e,t){let o=a.useId(),i=a.useMemo(()=>({labelId:`${o}label`,descriptionId:`${o}description`,errorId:`${o}error`,controlId:`${o}control`}),[o]),[n,s]=a.useState(()=>({controlId:"",errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0})),l=(0,oe.useCallbackRef)(r.onValidityChange),d=a.useMemo(()=>new T({...i,grouped:e,onSnapshotChange:u=>{s(u);let{controlId:F,...Ce}=u;l(Ce)},announce:te.announce}),[i,e,l]);a.useEffect(()=>{let u=t.current;if(u)return d.connect(u),s(d.state),()=>d.disconnect()},[d,t]),a.useEffect(()=>{d.setProps({validate:r.validate,mode:r.mode,errors:r.errors,value:r.value,name:r.name,getCharacterCountMessage:r.getCharacterCountMessage,invalidMessage:r.invalidMessage}),d.sync()});let m=a.useCallback(u=>d.setCharacterCount(u),[d]);return{...i,controlId:n.controlId||void 0,errors:n.errors,grouped:e,count:n.count,setCharacterCount:m,getCharacterCountMessage:r.getCharacterCountMessage}}var H=a.forwardRef(({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l,...d},m)=>{let h=a.useRef(null),u=ne({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l},!1,h),F=(0,V.useComposedRefs)(m,h);return(0,E.jsx)(ie,{...u,children:(0,E.jsx)(k.Primitive.div,{...d,...(0,re.skdxPart)("field","root",d.className),ref:F})})});H.displayName="Field";var w=a.forwardRef(({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l,...d},m)=>{let h=a.useRef(null),u=ne({validate:r,mode:e,errors:t,value:o,name:i,onValidityChange:n,getCharacterCountMessage:s,invalidMessage:l},!0,h),F=(0,V.useComposedRefs)(m,h);return(0,E.jsx)(ie,{...u,children:(0,E.jsx)(k.Primitive.fieldset,{...d,ref:F})})});w.displayName="Fieldset";var se=f(require("react"),1),U=require("../utils/part.cjs"),B=require("../utils/primitive.cjs");var $=require("react/jsx-runtime"),G=se.forwardRef((r,e)=>{let t=c("FieldLabel");return t.grouped?(0,$.jsx)(B.Primitive.legend,{id:t.labelId,...r,...(0,U.skdxPart)("field","label",r.className),ref:e}):(0,$.jsx)(B.Primitive.label,{id:t.labelId,htmlFor:t.controlId,...r,...(0,U.skdxPart)("field","label",r.className),ref:e})});G.displayName="FieldLabel";var ae=f(require("react"),1),le=require("../utils/part.cjs"),de=require("../utils/primitive.cjs");var ue=require("react/jsx-runtime"),j=ae.forwardRef((r,e)=>{let t=c("FieldDescription");return(0,ue.jsx)(de.Primitive.span,{id:t.descriptionId,[P]:"",...r,...(0,le.skdxPart)("field","description",r.className),ref:e})});j.displayName="FieldDescription";var ce=f(require("react"),1),he=require("../utils/part.cjs"),pe=require("../utils/primitive.cjs");var me=require("react/jsx-runtime"),Y=ce.forwardRef(({children:r,...e},t)=>{let o=c("FieldError");return o.errors.length===0?null:(0,me.jsx)(pe.Primitive.span,{id:o.errorId,[R]:"",...e,...(0,he.skdxPart)("field","error",e.className),ref:t,children:r??o.errors.join(" ")})});Y.displayName="FieldError";var A=f(require("react"),1),fe=require("../utils/part.cjs"),ve=require("../utils/primitive.cjs");var ge=require("react/jsx-runtime"),q=A.forwardRef(({maxLength:r,threshold:e=0,children:t,...o},i)=>{let n=c("FieldCharacterCount"),{setCharacterCount:s}=n;if(A.useEffect(()=>(s({maxLength:r,threshold:e}),()=>s(null)),[s,r,e]),!C(n.count,r,e))return null;let l=r-n.count;return(0,ge.jsx)(ve.Primitive.span,{[I]:"","data-over-limit":l<0?"":void 0,...o,...(0,fe.skdxPart)("field","character-count",o.className),ref:i,children:t??(n.getCharacterCountMessage??g)(l)})});q.displayName="FieldCharacterCount";0&&(module.exports={CHARACTER_COUNT_ANNOUNCE_DELAY_MS,FIELD_CHARACTER_COUNT_ATTRIBUTE,FIELD_CONTROL_ATTRIBUTE,FIELD_CONTROL_SELECTOR,FIELD_VALIDITY_CHANGE_EVENT,Field,FieldCharacterCount,FieldDescription,FieldError,FieldLabel,Fieldset,NATIVE_INVALID_FALLBACK_MESSAGE,characterCountMessage,characterCountVisible,collectFieldErrors,errorSummaryScope,findFieldControl,focusFieldTarget});