@ariakit/core 0.0.1 → 0.1.0

package/esm/composite/composite-store.d.ts

@@ -0,0 +1,202 @@
+import type { CollectionStoreFunctions, CollectionStoreItem, CollectionStoreOptions, CollectionStoreState } from "../collection/collection-store.js";
+import type { Store, StoreOptions, StoreProps } from "../utils/store.js";
+import type { SetState } from "../utils/types.js";
+type Orientation = "horizontal" | "vertical" | "both";
+type Item = CollectionStoreItem & {
+    rowId?: string;
+    disabled?: boolean;
+    children?: string;
+};
+/**
+ * Creates a composite store.
+ */
+export declare function createCompositeStore<T extends Item = Item>(props?: CompositeStoreProps<T>): CompositeStore<T>;
+export type CompositeStoreOrientation = Orientation;
+export type CompositeStoreItem = Item;
+export interface CompositeStoreState<T extends Item = Item> extends CollectionStoreState<T> {
+    /**
+     * The composite element.
+     */
+    baseElement: HTMLElement | null;
+    /**
+     * If enabled, the composite element will act as an
+     * [aria-activedescendant](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant)
+     * container instead of [roving
+     * tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex).
+     * DOM focus will remain on the composite element while its items receive
+     * virtual focus.
+     * @default false
+     */
+    virtualFocus: boolean;
+    /**
+     * Defines the orientation of the composite widget. If the composite has a
+     * single row or column (one-dimensional), the `orientation` value determines
+     * which arrow keys can be used to move focus:
+     *   - `both`: all arrow keys work.
+     *   - `horizontal`: only left and right arrow keys work.
+     *   - `vertical`: only up and down arrow keys work.
+     *
+     * It doesn't have any effect on two-dimensional composites.
+     * @default "both"
+     */
+    orientation: Orientation;
+    /**
+     * Determines how the `next` and `previous` functions will behave. If `rtl` is
+     * set to `true`, they will be inverted. This only affects the composite
+     * widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
+     * @default false
+     */
+    rtl: boolean;
+    /**
+     * Determines how the focus behaves when the user reaches the end of the
+     * composite widget.
+     *
+     * On one-dimensional composites:
+     *   - `true` loops from the last item to the first item and vice-versa.
+     *   - `horizontal` loops only if `orientation` is `horizontal` or not set.
+     *   - `vertical` loops only if `orientation` is `vertical` or not set.
+     *   - If `includesBaseElement` is set to `true` (or `activeId` is initially
+     *     set to `null`), the composite element will be focused in between the
+     *     last and first items.
+     *
+     * On two-dimensional composites (when using `CompositeRow`):
+     *   - `true` loops from the last row/column item to the first item in the
+     *     same row/column and vice-versa. If it's the last item in the last row,
+     *     it moves to the first item in the first row and vice-versa.
+     *   - `horizontal` loops only from the last row item to the first item in the
+     *     same row.
+     *   - `vertical` loops only from the last column item to the first item in
+     *     the column row.
+     *   - If `includesBaseElement` is set to `true` (or `activeId` is initially
+     *     set to `null`), vertical loop will have no effect as moving down from
+     *     the last row or up from the first row will focus the composite element.
+     *   - If `focusWrap` matches the value of `focusLoop`, it'll wrap between the
+     *     last item in the last row or column and the first item in the first row
+     *     or column and vice-versa.
+     * @default false
+     */
+    focusLoop: boolean | Orientation;
+    /**
+     * **Works only on two-dimensional composites**. If enabled, moving to the
+     * next item from the last one in a row or column will focus the first item in
+     * the next row or column and vice-versa.
+     *   - `true` wraps between rows and columns.
+     *   - `horizontal` wraps only between rows.
+     *   - `vertical` wraps only between columns.
+     *   - If `focusLoop` matches the value of `focusWrap`, it'll wrap between the
+     *     last item in the last row or column and the first item in the first row
+     *     or column and vice-versa.
+     * @default false
+     */
+    focusWrap: boolean | Orientation;
+    /**
+     * **Works only on two-dimensional composites**. If enabled, moving up or down
+     * when there's no next item or when the next item is disabled will shift to
+     * the item right before it.
+     * @default false
+     */
+    focusShift: boolean;
+    /**
+     * The number of times the `move` function has been called.
+     */
+    moves: number;
+    /**
+     * Indicates whether the composite element should be included in the focus
+     * order.
+     * @default false
+     */
+    includesBaseElement: boolean;
+    /**
+     * The current focused item `id`.
+     *   - `null` focuses the base composite element and users will be able to
+     *     navigate out of it using arrow keys.
+     *   - If `activeId` is initially set to `null`, the `includesBaseElement`
+     *     prop will also default to `true`, which means the base composite
+     *     element itself will have focus and users will be able to navigate to it
+     *     using arrow keys.
+     */
+    activeId: string | null | undefined;
+}
+export interface CompositeStoreFunctions<T extends Item = Item> extends CollectionStoreFunctions<T> {
+    /**
+     * Sets the `baseElement`.
+     */
+    setBaseElement: SetState<CompositeStoreState<T>["baseElement"]>;
+    /**
+     * Sets the `activeId` state without moving focus. If you want to move focus,
+     * use the `move` function instead.
+     * @example
+     * // Sets the composite element as the active item
+     * store.setActiveId(null);
+     * // Sets the item with id "item-1" as the active item
+     * store.setActiveId("item-1");
+     * // Sets the next item as the active item
+     * store.setActiveId(store.next());
+     */
+    setActiveId: SetState<CompositeStoreState<T>["activeId"]>;
+    /**
+     * Moves focus to a given item id and sets it as the active item. Passing
+     * `null` will focus the composite element itself.
+     * @param id The item id to move focus to.
+     * @example
+     * // Moves focus to the composite element
+     * store.move(null);
+     * // Moves focus to the item with id "item-1"
+     * store.move("item-1");
+     * // Moves focus to the next item
+     * store.move(store.next());
+     */
+    move: (id?: string | null) => void;
+    /**
+     * Returns the id of the next item based on the current `activeId` state.
+     * @param skip The number of items to skip. Defaults to 1.
+     * @example
+     * const nextId = store.next();
+     * const nextNextId = store.next(2);
+     */
+    next: (skip?: number) => string | null | undefined;
+    /**
+     * Returns the id of the previous item based on the current `activeId` state.
+     * @param skip The number of items to skip. Defaults to 1.
+     * @example
+     * const previousId = store.previous();
+     * const previousPreviousId = store.previous(2);
+     */
+    previous: (skip?: number) => string | null | undefined;
+    /**
+     * Returns the id of the item above based on the current `activeId` state.
+     * @param skip The number of items to skip. Defaults to 1.
+     * @example
+     * const upId = store.up();
+     * const upUpId = store.up(2);
+     */
+    up: (skip?: number) => string | null | undefined;
+    /**
+     * Returns the id of the item below based on the current `activeId` state.
+     * @param skip The number of items to skip. Defaults to 1.
+     * @example
+     * const downId = store.down();
+     * const downDownId = store.down(2);
+     */
+    down: (skip?: number) => string | null | undefined;
+    /**
+     * Returns the id of the first item.
+     */
+    first: () => string | null | undefined;
+    /**
+     * Returns the id of the last item.
+     */
+    last: () => string | null | undefined;
+}
+export interface CompositeStoreOptions<T extends Item = Item> extends StoreOptions<CompositeStoreState<T>, "virtualFocus" | "orientation" | "rtl" | "focusLoop" | "focusWrap" | "focusShift" | "includesBaseElement" | "activeId">, CollectionStoreOptions<T> {
+    /**
+     * The composite item id that should be active by default when the composite
+     * widget is rendered. If `null`, the composite element itself will have focus
+     * and users will be able to navigate to it using arrow keys. If `undefined`,
+     * the first enabled item will be focused.
+     */
+    defaultActiveId?: CompositeStoreState<T>["activeId"];
+}
+export type CompositeStoreProps<T extends Item = Item> = CompositeStoreOptions<T> & StoreProps<CompositeStoreState<T>>;
+export type CompositeStore<T extends Item = Item> = CompositeStoreFunctions<T> & Store<CompositeStoreState<T>>;
+export {};

package/esm/composite/composite-store.js

@@ -0,0 +1,11 @@
+import {
+  createCompositeStore
+} from "../__chunks/6U25WEDX.js";
+import "../__chunks/L7KN5AYP.js";
+import "../__chunks/UOJSZ35L.js";
+import "../__chunks/KLKI3AIB.js";
+import "../__chunks/UVCATTRC.js";
+import "../__chunks/5XEKIOCW.js";
+export {
+  createCompositeStore
+};

package/esm/dialog/dialog-store.d.ts

@@ -0,0 +1,10 @@
+import type { DisclosureStore, DisclosureStoreFunctions, DisclosureStoreOptions, DisclosureStoreProps, DisclosureStoreState } from "../disclosure/disclosure-store.js";
+/**
+ * Creates a dialog store.
+ */
+export declare function createDialogStore(props?: DialogStoreProps): DialogStore;
+export type DialogStoreState = DisclosureStoreState;
+export type DialogStoreFunctions = DisclosureStoreFunctions;
+export type DialogStoreOptions = DisclosureStoreOptions;
+export type DialogStoreProps = DisclosureStoreProps;
+export type DialogStore = DisclosureStore;

package/esm/dialog/dialog-store.js

@@ -0,0 +1,9 @@
+import {
+  createDialogStore
+} from "../__chunks/ADRUFBEO.js";
+import "../__chunks/HCKYJLMC.js";
+import "../__chunks/UOJSZ35L.js";
+import "../__chunks/KLKI3AIB.js";
+export {
+  createDialogStore
+};

package/esm/disclosure/disclosure-store.d.ts

@@ -0,0 +1,87 @@
+import type { Store, StoreOptions, StoreProps } from "../utils/store.js";
+import type { SetState } from "../utils/types.js";
+/**
+ * Creates a disclosure store.
+ */
+export declare function createDisclosureStore(props?: DisclosureStoreProps): DisclosureStore;
+export interface DisclosureStoreState {
+    /**
+     * The visibility state of the content.
+     * @default false
+     */
+    open: boolean;
+    /**
+     * The mounted state of the content. If `animated` is `false` or not defined,
+     * this will be the same as `open`. Otherwise, it will wait for the animation
+     * to complete before becoming `false` so the content is not unmounted while
+     * animating.
+     */
+    mounted: boolean;
+    /**
+     * Determines whether the content should animate when it is shown or hidden.
+     *   - If `true`, the `animating` state will be `true` when the content is
+     *     shown or hidden and it will wait for `stopAnimation` to be called or a
+     *     CSS animation/transition to end before becoming `false`.
+     *   - If it's set to a number, the `animating` state will be `true` when the
+     *     content is shown or hidden and it will wait for the number of
+     *     milliseconds to pass before becoming `false`.
+     * @default false
+     */
+    animated: boolean | number;
+    /**
+     * Whether the content is currently animating.
+     */
+    animating: boolean;
+    /**
+     * The content element that is being shown or hidden.
+     */
+    contentElement: HTMLElement | null;
+    /**
+     * The disclosure button element that toggles the content.
+     */
+    disclosureElement: HTMLElement | null;
+}
+export interface DisclosureStoreFunctions {
+    /**
+     * Sets the `open` state.
+     * @example
+     * store.setOpen(true);
+     * store.setOpen((open) => !open);
+     */
+    setOpen: SetState<DisclosureStoreState["open"]>;
+    /**
+     * Sets the `open` state to `true`.
+     */
+    show: () => void;
+    /**
+     * Sets the `open` state to `false`.
+     */
+    hide: () => void;
+    /**
+     * Toggles the `open` state.
+     */
+    toggle: () => void;
+    /**
+     * Sets the `animating` state to `false`, which will automatically set the
+     * `mounted` state to `false` if it was `true`. This means that the content
+     * element can be safely unmounted.
+     */
+    stopAnimation: () => void;
+    /**
+     * Sets the `contentElement` state.
+     */
+    setContentElement: SetState<DisclosureStoreState["contentElement"]>;
+    /**
+     * Sets the `disclosureElement` state.
+     */
+    setDisclosureElement: SetState<DisclosureStoreState["disclosureElement"]>;
+}
+export interface DisclosureStoreOptions extends StoreOptions<DisclosureStoreState, "open" | "animated"> {
+    /**
+     * The default visibility state of the content.
+     * @default false
+     */
+    defaultOpen?: DisclosureStoreState["open"];
+}
+export type DisclosureStoreProps = DisclosureStoreOptions & StoreProps<DisclosureStoreState>;
+export type DisclosureStore = DisclosureStoreFunctions & Store<DisclosureStoreState>;

package/esm/disclosure/disclosure-store.js

@@ -0,0 +1,8 @@
+import {
+  createDisclosureStore
+} from "../__chunks/HCKYJLMC.js";
+import "../__chunks/UOJSZ35L.js";
+import "../__chunks/KLKI3AIB.js";
+export {
+  createDisclosureStore
+};

package/esm/form/form-store.d.ts

@@ -0,0 +1,236 @@
+import type { CollectionStoreFunctions, CollectionStoreItem, CollectionStoreOptions, CollectionStoreState } from "../collection/collection-store.js";
+import type { Store, StoreOptions, StoreProps } from "../utils/store.js";
+import type { AnyObject, PickRequired, SetState, SetStateAction } from "../utils/types.js";
+import type { DeepMap, DeepPartial, Names, StringLike } from "./types.js";
+type Values = AnyObject;
+type ErrorMessage = string | undefined | null;
+type Item = CollectionStoreItem & {
+    type: "field" | "label" | "description" | "error" | "button";
+    name: string;
+};
+export declare function hasMessages(object: Values): boolean;
+export declare function get<T>(values: Values, path: StringLike | string[], defaultValue?: T): T;
+/**
+ * Creates a form store.
+ */
+export declare function createFormStore<T extends Values = Values>(props: PickRequired<FormStoreProps<T>, "values" | "defaultValues" | "errors" | "defaultErrors" | "touched" | "defaultTouched">): FormStore<T>;
+export declare function createFormStore(props: FormStoreProps): FormStore;
+export type FormStoreCallback<T extends FormStoreState = FormStoreState> = (state: T) => void | Promise<void>;
+export type FormStoreValues = Values;
+export type FormStoreItem = Item;
+export interface FormStoreState<T extends Values = Values> extends CollectionStoreState<Item> {
+    /**
+     * Form values.
+     * @default {}
+     */
+    values: T;
+    /**
+     * Form errors.
+     */
+    errors: DeepPartial<DeepMap<T, ErrorMessage>>;
+    /**
+     * The touched state of the form.
+     */
+    touched: DeepPartial<DeepMap<T, boolean>>;
+    /**
+     * Whether the form is valid.
+     */
+    valid: boolean;
+    /**
+     * Whether the form is validating.
+     */
+    validating: boolean;
+    /**
+     * Whether the form is submitting.
+     */
+    submitting: boolean;
+    /**
+     * The number of times `form.submit` has been called with a successful
+     * response.
+     */
+    submitSucceed: number;
+    /**
+     * The number of times `form.submit` has been called with an error response.
+     */
+    submitFailed: number;
+}
+export interface FormStoreFunctions<T extends Values = Values> extends CollectionStoreFunctions<Item> {
+    /**
+     * An object containing the names of the form fields for type-safety.
+     * @example
+     * store.names.name; // "name"
+     * store.names.name.first; // "name.first"
+     * store.names.name.last; // "name.last"
+     */
+    names: Names<T>;
+    /**
+     * Sets the `values` state.
+     * @example
+     * store.setValues({ name: "John" });
+     * store.setValues((values) => ({ ...values, name: "John" }));
+     */
+    setValues: SetState<FormStoreState<T>["values"]>;
+    /**
+     * Retrieves a field value.
+     * @param name The field name.
+     * @example
+     * const nameValue = store.getValue("name");
+     * // Can also use store.names for type-safety.
+     * const emailValue = store.getValue(store.names.email);
+     */
+    getValue: <T = any>(name: StringLike) => T;
+    /**
+     * Sets a field value.
+     * @param name The field name.
+     * @param value The field value.
+     * @example
+     * store.setValue("name", "John");
+     * store.setValue("name", (value) => value + " Doe");
+     * // Can also use store.names for type-safety.
+     * store.setValue(store.names.name, "John");
+     */
+    setValue: <T>(name: StringLike, value: SetStateAction<T>) => void;
+    /**
+     * Pushes a value to an array field.
+     * @param name The array field name.
+     * @param value The value to push.
+     * @example
+     * store.pushValue("tags", "new tag");
+     * store.pushValue("tags", { id: 1, name: "new tag" });
+     * // Can also use store.names for type-safety.
+     * store.pushValue(store.names.tags, "new tag");
+     */
+    pushValue: <T>(name: StringLike, value: T) => void;
+    /**
+     * Removes a value from an array field.
+     * @param name The array field name.
+     * @param index The index of the value to remove.
+     * @example
+     * store.removeValue("tags", 0);
+     * store.removeValue("tags", 1);
+     * // Can also use store.names for type-safety.
+     * store.removeValue(store.names.tags, 0);
+     */
+    removeValue: (name: StringLike, index: number) => void;
+    /**
+     * Sets the `errors` state.
+     * @example
+     * store.setErrors({ name: "Name is required" });
+     * store.setErrors((errors) => ({ ...errors, name: "Name is required" }));
+     */
+    setErrors: SetState<FormStoreState<T>["errors"]>;
+    /**
+     * Retrieves a field error.
+     * @param name The field name.
+     * @example
+     * const nameError = store.getError("name");
+     * // Can also use store.names for type-safety.
+     * const emailError = store.getError(store.names.email);
+     */
+    getError: (name: StringLike) => ErrorMessage;
+    /**
+     * Sets a field error.
+     * @param name The field name.
+     * @param error The field error.
+     * @example
+     * store.setError("name", "Name is required");
+     * store.setError("name", (error) => error + "!");
+     * // Can also use store.names for type-safety.
+     * store.setError(store.names.name, "Name is required");
+     */
+    setError: (name: StringLike, error: SetStateAction<ErrorMessage>) => void;
+    /**
+     * Sets the `touched` state.
+     * @example
+     * store.setTouched({ name: true });
+     * store.setTouched((touched) => ({ ...touched, name: true }));
+     */
+    setTouched: SetState<FormStoreState<T>["touched"]>;
+    /**
+     * Retrieves a field touched state.
+     * @param name The field name.
+     * @example
+     * const nameTouched = store.getFieldTouched("name");
+     * // Can also use store.names for type-safety.
+     * const emailTouched = store.getFieldTouched(store.names.email);
+     */
+    getFieldTouched: (name: StringLike) => boolean;
+    /**
+     * Sets a field touched state.
+     * @param name The field name.
+     * @param value The field touched state.
+     * @example
+     * store.setFieldTouched("name", true);
+     * store.setFieldTouched("name", (value) => !value);
+     * // Can also use store.names for type-safety.
+     * store.setFieldTouched(store.names.name, true);
+     */
+    setFieldTouched: (name: StringLike, value: SetStateAction<boolean>) => void;
+    /**
+     * Function that accepts a callback that will be used to validate the form
+     * when `validate` is called. It returns a cleanup function that will remove
+     * the callback.
+     * @param callback The callback function.
+     * @example
+     * const cleanup = store.onValidate(async (state) => {
+     *   const errors = await api.validate(state.values);
+     *   if (errors) {
+     *     store.setErrors(errors);
+     *   }
+     * });
+     */
+    onValidate: (callback: FormStoreCallback<FormStoreState<T>>) => void;
+    /**
+     * Function that accepts a callback that will be used to submit the form
+     * when `submit` is called. It returns a cleanup function that will remove
+     * the callback.
+     * @param callback The callback function.
+     * @example
+     * const cleanup = store.onSubmit(async (state) => {
+     *   try {
+     *     await api.submit(state.values);
+     *   } catch (errors) {
+     *     store.setErrors(errors);
+     *   }
+     * });
+     */
+    onSubmit: (callback: FormStoreCallback<FormStoreState<T>>) => void;
+    /**
+     * Validates the form.
+     * @example
+     * if (await store.validate()) {
+     *  // Form is valid.
+     * }
+     */
+    validate: () => Promise<boolean>;
+    /**
+     * Submits the form. This also triggers validation.
+     * @example
+     * if (await form.submit()) {
+     *   // Form is submitted.
+     * }
+     */
+    submit: () => Promise<boolean>;
+    /**
+     * Resets the form to its default values.
+     */
+    reset: () => void;
+}
+export interface FormStoreOptions<T extends Values = Values> extends StoreOptions<FormStoreState<T>, "values" | "errors" | "touched">, CollectionStoreOptions<Item> {
+    /**
+     * The default values of the form.
+     * @default {}
+     */
+    defaultValues?: FormStoreState<T>["values"];
+    /**
+     * The default errors of the form.
+     */
+    defaultErrors?: FormStoreState<T>["errors"];
+    /**
+     * The default touched state of the form.
+     */
+    defaultTouched?: FormStoreState<T>["touched"];
+}
+export type FormStoreProps<T extends Values = Values> = FormStoreOptions<T> & StoreProps<FormStoreState<T>>;
+export type FormStore<T extends Values = Values> = FormStoreFunctions<T> & Store<FormStoreState<T>>;
+export {};